zhongwei/gh-igpastor-sng-claude-marketplace-plugins-sngular-pm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
694b4f5c2c5ee12f101777318c2a9716427582c2
gh-igpastor-sng-claude-mark…/commands/sng-repo.md
Zhongwei Li 694b4f5c2c Initial commit
2025-11-29 18:48:05 +08:00

13 KiB
Raw Blame History

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

#!/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

#!/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

# 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

#!/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

# 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:

    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 View Git Blame Copy Permalink