Initial commit
This commit is contained in:
Zhongwei Li
607
commands/sng-repo.md
Normal file
607
commands/sng-repo.md
Normal file
@@ -0,0 +1,607 @@
|
||||
# GitHub Repository Management Command
|
||||
|
||||
You are helping the user manage GitHub repositories, including setup, configuration, and administrative tasks following Sngular's best practices.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Determine the action**:
|
||||
- View repository information
|
||||
- Clone or fork repository
|
||||
- Configure repository settings
|
||||
- Manage branches and protection rules
|
||||
- Set up webhooks and integrations
|
||||
- Manage collaborators and teams
|
||||
- Configure Actions and workflows
|
||||
- Archive or transfer repository
|
||||
|
||||
2. **Verify GitHub access**:
|
||||
- Check `gh` CLI authentication
|
||||
- Verify user permissions
|
||||
- Confirm organization membership if needed
|
||||
|
||||
## GitHub CLI Commands
|
||||
|
||||
### Repository Information
|
||||
|
||||
```bash
|
||||
# View current repository
|
||||
gh repo view
|
||||
|
||||
# View specific repository
|
||||
gh repo view OWNER/REPO
|
||||
|
||||
# View in browser
|
||||
gh repo view OWNER/REPO --web
|
||||
|
||||
# Get repository details as JSON
|
||||
gh repo view OWNER/REPO --json name,description,owner,url,isPrivate,defaultBranch
|
||||
```
|
||||
|
||||
### Creating Repositories
|
||||
|
||||
```bash
|
||||
# Create new repository
|
||||
gh repo create my-new-repo --public --description "My project description"
|
||||
|
||||
# Create private repository
|
||||
gh repo create my-private-repo --private
|
||||
|
||||
# Create with README and license
|
||||
gh repo create my-repo --public --add-readme --license mit
|
||||
|
||||
# Create from template
|
||||
gh repo create my-project --template OWNER/TEMPLATE-REPO --public
|
||||
|
||||
# Create in organization
|
||||
gh repo create ORGANIZATION/repo-name --public
|
||||
|
||||
# Clone after creation
|
||||
gh repo create my-repo --public --clone
|
||||
```
|
||||
|
||||
### Cloning and Forking
|
||||
|
||||
```bash
|
||||
# Clone repository
|
||||
gh repo clone OWNER/REPO
|
||||
|
||||
# Clone to specific directory
|
||||
gh repo clone OWNER/REPO ./my-directory
|
||||
|
||||
# Fork repository
|
||||
gh repo fork OWNER/REPO
|
||||
|
||||
# Fork and clone
|
||||
gh repo fork OWNER/REPO --clone
|
||||
|
||||
# Fork to organization
|
||||
gh repo fork OWNER/REPO --org ORGANIZATION
|
||||
```
|
||||
|
||||
### Repository Settings
|
||||
|
||||
```bash
|
||||
# Edit repository details
|
||||
gh repo edit OWNER/REPO --description "New description"
|
||||
|
||||
# Enable/disable features
|
||||
gh repo edit OWNER/REPO --enable-wiki=true
|
||||
gh repo edit OWNER/REPO --enable-issues=true
|
||||
gh repo edit OWNER/REPO --enable-projects=true
|
||||
|
||||
# Change default branch
|
||||
gh repo edit OWNER/REPO --default-branch main
|
||||
|
||||
# Set homepage URL
|
||||
gh repo edit OWNER/REPO --homepage "https://example.com"
|
||||
|
||||
# Add topics
|
||||
gh repo edit OWNER/REPO --add-topic "javascript,react,frontend"
|
||||
|
||||
# Change visibility
|
||||
gh repo edit OWNER/REPO --visibility private
|
||||
```
|
||||
|
||||
### Branch Management
|
||||
|
||||
```bash
|
||||
# List branches
|
||||
gh api repos/OWNER/REPO/branches
|
||||
|
||||
# Get default branch
|
||||
gh repo view OWNER/REPO --json defaultBranchRef --jq '.defaultBranchRef.name'
|
||||
|
||||
# Rename default branch (requires git)
|
||||
git branch -m master main
|
||||
git push -u origin main
|
||||
gh repo edit OWNER/REPO --default-branch main
|
||||
git push origin --delete master
|
||||
```
|
||||
|
||||
### Branch Protection
|
||||
|
||||
```bash
|
||||
# View branch protection
|
||||
gh api repos/OWNER/REPO/branches/main/protection
|
||||
|
||||
# Enable branch protection (via API)
|
||||
gh api -X PUT repos/OWNER/REPO/branches/main/protection \
|
||||
-f required_status_checks='{"strict":true,"contexts":["ci/test"]}' \
|
||||
-f enforce_admins=true \
|
||||
-f required_pull_request_reviews='{"required_approving_review_count":2}' \
|
||||
-f restrictions=null
|
||||
|
||||
# Require PR reviews
|
||||
gh api -X PUT repos/OWNER/REPO/branches/main/protection \
|
||||
-f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}'
|
||||
|
||||
# Require status checks
|
||||
gh api -X PUT repos/OWNER/REPO/branches/main/protection/required_status_checks \
|
||||
-f strict=true \
|
||||
-f contexts='["ci/test","ci/lint"]'
|
||||
```
|
||||
|
||||
### Collaborators and Teams
|
||||
|
||||
```bash
|
||||
# List collaborators
|
||||
gh api repos/OWNER/REPO/collaborators
|
||||
|
||||
# Add collaborator
|
||||
gh api -X PUT repos/OWNER/REPO/collaborators/USERNAME \
|
||||
-f permission=push
|
||||
|
||||
# Remove collaborator
|
||||
gh api -X DELETE repos/OWNER/REPO/collaborators/USERNAME
|
||||
|
||||
# List teams with access (organization repos)
|
||||
gh api repos/ORGANIZATION/REPO/teams
|
||||
|
||||
# Add team
|
||||
gh api -X PUT repos/ORGANIZATION/REPO/teams/TEAM-SLUG \
|
||||
-f permission=push
|
||||
|
||||
# Permission levels: pull, push, admin, maintain, triage
|
||||
```
|
||||
|
||||
### Repository Secrets
|
||||
|
||||
```bash
|
||||
# List secrets
|
||||
gh secret list --repo OWNER/REPO
|
||||
|
||||
# Set secret
|
||||
gh secret set SECRET_NAME --repo OWNER/REPO --body "secret-value"
|
||||
|
||||
# Set secret from file
|
||||
gh secret set SECRET_NAME --repo OWNER/REPO < secret.txt
|
||||
|
||||
# Delete secret
|
||||
gh secret delete SECRET_NAME --repo OWNER/REPO
|
||||
```
|
||||
|
||||
### Actions and Workflows
|
||||
|
||||
```bash
|
||||
# List workflows
|
||||
gh workflow list
|
||||
|
||||
# View workflow
|
||||
gh workflow view workflow.yml
|
||||
|
||||
# Run workflow
|
||||
gh workflow run workflow.yml
|
||||
|
||||
# View workflow runs
|
||||
gh run list
|
||||
|
||||
# View specific run
|
||||
gh run view RUN_ID
|
||||
|
||||
# Download artifacts
|
||||
gh run download RUN_ID
|
||||
|
||||
# Enable/disable workflow
|
||||
gh workflow enable workflow.yml
|
||||
gh workflow disable workflow.yml
|
||||
```
|
||||
|
||||
### Webhooks
|
||||
|
||||
```bash
|
||||
# List webhooks
|
||||
gh api repos/OWNER/REPO/hooks
|
||||
|
||||
# Create webhook
|
||||
gh api repos/OWNER/REPO/hooks \
|
||||
-f name=web \
|
||||
-f active=true \
|
||||
-f events='["push","pull_request"]' \
|
||||
-f config='{"url":"https://example.com/webhook","content_type":"json"}'
|
||||
|
||||
# Delete webhook
|
||||
gh api -X DELETE repos/OWNER/REPO/hooks/HOOK_ID
|
||||
```
|
||||
|
||||
### Repository Analytics
|
||||
|
||||
```bash
|
||||
# View traffic (views, clones)
|
||||
gh api repos/OWNER/REPO/traffic/views
|
||||
gh api repos/OWNER/REPO/traffic/clones
|
||||
|
||||
# Popular content
|
||||
gh api repos/OWNER/REPO/traffic/popular/paths
|
||||
|
||||
# Referrers
|
||||
gh api repos/OWNER/REPO/traffic/popular/referrers
|
||||
|
||||
# Languages
|
||||
gh api repos/OWNER/REPO/languages
|
||||
|
||||
# Contributors
|
||||
gh api repos/OWNER/REPO/contributors
|
||||
```
|
||||
|
||||
### Repository Maintenance
|
||||
|
||||
```bash
|
||||
# Archive repository
|
||||
gh repo archive OWNER/REPO
|
||||
|
||||
# Unarchive repository
|
||||
gh repo archive OWNER/REPO --unarchive
|
||||
|
||||
# Delete repository (careful!)
|
||||
gh repo delete OWNER/REPO --confirm
|
||||
|
||||
# Transfer repository
|
||||
gh api -X POST repos/OWNER/REPO/transfer \
|
||||
-f new_owner=NEW-OWNER
|
||||
```
|
||||
|
||||
## Common Setup Tasks
|
||||
|
||||
### Initialize New Repository
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# setup-repo.sh
|
||||
|
||||
REPO_NAME=$1
|
||||
ORG_NAME=${2:-}
|
||||
DESCRIPTION=${3:-""}
|
||||
|
||||
# Create repository
|
||||
if [ -n "$ORG_NAME" ]; then
|
||||
gh repo create "$ORG_NAME/$REPO_NAME" \
|
||||
--public \
|
||||
--description "$DESCRIPTION" \
|
||||
--add-readme \
|
||||
--license mit \
|
||||
--clone
|
||||
else
|
||||
gh repo create "$REPO_NAME" \
|
||||
--public \
|
||||
--description "$DESCRIPTION" \
|
||||
--add-readme \
|
||||
--license mit \
|
||||
--clone
|
||||
fi
|
||||
|
||||
cd "$REPO_NAME" || exit
|
||||
|
||||
# Initialize git flow
|
||||
git checkout -b develop
|
||||
|
||||
# Create .gitignore
|
||||
cat > .gitignore <<EOF
|
||||
node_modules/
|
||||
.env
|
||||
.DS_Store
|
||||
dist/
|
||||
build/
|
||||
*.log
|
||||
EOF
|
||||
|
||||
# Create basic README
|
||||
cat > README.md <<EOF
|
||||
# $REPO_NAME
|
||||
|
||||
$DESCRIPTION
|
||||
|
||||
## Installation
|
||||
|
||||
\`\`\`bash
|
||||
npm install
|
||||
\`\`\`
|
||||
|
||||
## Usage
|
||||
|
||||
\`\`\`bash
|
||||
npm start
|
||||
\`\`\`
|
||||
|
||||
## Testing
|
||||
|
||||
\`\`\`bash
|
||||
npm test
|
||||
\`\`\`
|
||||
|
||||
## Contributing
|
||||
|
||||
Please read CONTRIBUTING.md for details.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
EOF
|
||||
|
||||
# Commit initial setup
|
||||
git add .
|
||||
git commit -m "Initial repository setup"
|
||||
git push origin main
|
||||
git push origin develop
|
||||
|
||||
echo "Repository $REPO_NAME created and initialized!"
|
||||
```
|
||||
|
||||
### Configure Branch Protection
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# protect-main-branch.sh
|
||||
|
||||
OWNER=$1
|
||||
REPO=$2
|
||||
|
||||
echo "Configuring branch protection for main branch..."
|
||||
|
||||
# Require PR reviews
|
||||
gh api -X PUT repos/$OWNER/$REPO/branches/main/protection \
|
||||
--input - <<EOF
|
||||
{
|
||||
"required_status_checks": {
|
||||
"strict": true,
|
||||
"contexts": ["ci/test", "ci/lint"]
|
||||
},
|
||||
"enforce_admins": true,
|
||||
"required_pull_request_reviews": {
|
||||
"required_approving_review_count": 1,
|
||||
"dismiss_stale_reviews": true,
|
||||
"require_code_owner_reviews": true
|
||||
},
|
||||
"restrictions": null,
|
||||
"required_linear_history": true,
|
||||
"allow_force_pushes": false,
|
||||
"allow_deletions": false
|
||||
}
|
||||
EOF
|
||||
|
||||
echo "Branch protection configured!"
|
||||
```
|
||||
|
||||
### Setup GitHub Actions
|
||||
|
||||
```bash
|
||||
# Create .github/workflows directory
|
||||
mkdir -p .github/workflows
|
||||
|
||||
# Create CI workflow
|
||||
cat > .github/workflows/ci.yml <<'EOF'
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, develop]
|
||||
pull_request:
|
||||
branches: [main, develop]
|
||||
|
||||
jobs:
|
||||
test:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: 'npm'
|
||||
- run: npm ci
|
||||
- run: npm test
|
||||
- run: npm run lint
|
||||
|
||||
build:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 20
|
||||
cache: 'npm'
|
||||
- run: npm ci
|
||||
- run: npm run build
|
||||
EOF
|
||||
|
||||
git add .github/workflows/ci.yml
|
||||
git commit -m "Add CI workflow"
|
||||
git push
|
||||
```
|
||||
|
||||
### Configure Repository Labels
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# setup-labels.sh
|
||||
|
||||
OWNER=$1
|
||||
REPO=$2
|
||||
|
||||
# Delete default labels
|
||||
gh label delete bug --repo $OWNER/$REPO --yes
|
||||
gh label delete documentation --repo $OWNER/$REPO --yes
|
||||
gh label delete enhancement --repo $OWNER/$REPO --yes
|
||||
|
||||
# Create custom labels
|
||||
gh label create "type: bug" --color "d73a4a" --description "Something isn't working" --repo $OWNER/$REPO
|
||||
gh label create "type: feature" --color "0075ca" --description "New feature or request" --repo $OWNER/$REPO
|
||||
gh label create "type: docs" --color "0075ca" --description "Documentation improvements" --repo $OWNER/$REPO
|
||||
gh label create "type: refactor" --color "fbca04" --description "Code refactoring" --repo $OWNER/$REPO
|
||||
|
||||
gh label create "priority: critical" --color "b60205" --description "Critical priority" --repo $OWNER/$REPO
|
||||
gh label create "priority: high" --color "d93f0b" --description "High priority" --repo $OWNER/$REPO
|
||||
gh label create "priority: medium" --color "fbca04" --description "Medium priority" --repo $OWNER/$REPO
|
||||
gh label create "priority: low" --color "0e8a16" --description "Low priority" --repo $OWNER/$REPO
|
||||
|
||||
gh label create "status: ready" --color "0e8a16" --description "Ready for development" --repo $OWNER/$REPO
|
||||
gh label create "status: in-progress" --color "fbca04" --description "Currently being worked on" --repo $OWNER/$REPO
|
||||
gh label create "status: blocked" --color "d93f0b" --description "Blocked by dependencies" --repo $OWNER/$REPO
|
||||
gh label create "status: needs-review" --color "0075ca" --description "Needs code review" --repo $OWNER/$REPO
|
||||
|
||||
echo "Labels configured!"
|
||||
```
|
||||
|
||||
### Setup Issue Templates
|
||||
|
||||
```bash
|
||||
# Create issue templates directory
|
||||
mkdir -p .github/ISSUE_TEMPLATE
|
||||
|
||||
# Bug report template
|
||||
cat > .github/ISSUE_TEMPLATE/bug_report.md <<'EOF'
|
||||
---
|
||||
name: Bug Report
|
||||
about: Create a report to help us improve
|
||||
title: '[BUG] '
|
||||
labels: 'type: bug, status: triage'
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## Bug Description
|
||||
A clear description of what the bug is.
|
||||
|
||||
## Steps to Reproduce
|
||||
1. Go to '...'
|
||||
2. Click on '...'
|
||||
3. See error
|
||||
|
||||
## Expected Behavior
|
||||
What you expected to happen.
|
||||
|
||||
## Actual Behavior
|
||||
What actually happened.
|
||||
|
||||
## Environment
|
||||
- OS: [e.g., macOS 14.0]
|
||||
- Browser: [e.g., Chrome 120]
|
||||
- Version: [e.g., 2.0.1]
|
||||
|
||||
## Additional Context
|
||||
Add any other context about the problem here.
|
||||
EOF
|
||||
|
||||
# Feature request template
|
||||
cat > .github/ISSUE_TEMPLATE/feature_request.md <<'EOF'
|
||||
---
|
||||
name: Feature Request
|
||||
about: Suggest an idea for this project
|
||||
title: '[FEATURE] '
|
||||
labels: 'type: feature, status: triage'
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
## Feature Description
|
||||
Clear description of the feature you'd like to see.
|
||||
|
||||
## Problem Statement
|
||||
What problem does this feature solve?
|
||||
|
||||
## Proposed Solution
|
||||
How should this feature work?
|
||||
|
||||
## Alternatives Considered
|
||||
What other approaches did you consider?
|
||||
|
||||
## Additional Context
|
||||
Add any other context or screenshots about the feature request.
|
||||
EOF
|
||||
|
||||
git add .github/ISSUE_TEMPLATE
|
||||
git commit -m "Add issue templates"
|
||||
git push
|
||||
```
|
||||
|
||||
## Repository Best Practices
|
||||
|
||||
### README Structure
|
||||
|
||||
A good README should include:
|
||||
1. Project title and description
|
||||
2. Installation instructions
|
||||
3. Usage examples
|
||||
4. API documentation (if applicable)
|
||||
5. Contributing guidelines
|
||||
6. License information
|
||||
7. Contact information
|
||||
8. Badges (build status, coverage, version)
|
||||
|
||||
### Branch Strategy
|
||||
|
||||
**Git Flow**:
|
||||
- `main` - Production-ready code
|
||||
- `develop` - Development branch
|
||||
- `feature/*` - Feature branches
|
||||
- `hotfix/*` - Emergency fixes
|
||||
- `release/*` - Release preparation
|
||||
|
||||
**GitHub Flow** (simpler):
|
||||
- `main` - Always deployable
|
||||
- `feature-branches` - Short-lived feature branches
|
||||
- Deploy from main
|
||||
|
||||
### Security Best Practices
|
||||
|
||||
1. **Enable security features**:
|
||||
```bash
|
||||
gh repo edit OWNER/REPO --enable-security-alerts=true
|
||||
gh repo edit OWNER/REPO --enable-vulnerability-alerts=true
|
||||
```
|
||||
|
||||
2. **Use branch protection**:
|
||||
- Require PR reviews
|
||||
- Require status checks
|
||||
- Enforce linear history
|
||||
- No force pushes
|
||||
|
||||
3. **Secrets management**:
|
||||
- Never commit secrets
|
||||
- Use GitHub Secrets
|
||||
- Rotate secrets regularly
|
||||
- Use separate secrets per environment
|
||||
|
||||
4. **Dependency management**:
|
||||
- Enable Dependabot
|
||||
- Review security advisories
|
||||
- Keep dependencies updated
|
||||
|
||||
### Documentation
|
||||
|
||||
Essential documentation files:
|
||||
- `README.md` - Project overview
|
||||
- `CONTRIBUTING.md` - Contribution guidelines
|
||||
- `CODE_OF_CONDUCT.md` - Community standards
|
||||
- `LICENSE` - License information
|
||||
- `CHANGELOG.md` - Version history
|
||||
- `.github/PULL_REQUEST_TEMPLATE.md` - PR template
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
Before managing repositories:
|
||||
1. "What do you want to do with the repository?"
|
||||
2. "Is this a new repository or existing one?"
|
||||
3. "Should it be public or private?"
|
||||
4. "Do you need branch protection rules?"
|
||||
5. "Should we set up CI/CD workflows?"
|
||||
6. "Do you need to add collaborators or teams?"
|
||||
7. "Should we configure issue templates?"
|
||||
|
||||
Ask the user: "What repository management task would you like to perform?"
|
||||
Reference in New Issue
Block a user