gh-igpastor-sng-claude-marketplace-plugins-sngular-pm/commands/sng-repo.md

# 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?"