# Skill: Repos

Manage GitHub repositories — create, clone, fork, view, configure settings, and manage collaborators.

## Commands Reference

### View Repository Info

```bash
# Current repo overview
gh repo view --json nameWithOwner,description,defaultBranchRef,visibility,homepageUrl,languages,licenseInfo,stargazerCount,forkCount

# Specific repo
gh repo view owner/repo --json nameWithOwner,description,defaultBranchRef,visibility

# Just the README (rendered)
gh repo view owner/repo

# Get default branch name
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'

# Get repo visibility
gh repo view --json visibility --jq '.visibility'

# List repo topics
gh repo view --json repositoryTopics --jq '.repositoryTopics[].name'
```

### List Repositories

```bash
# Your repos
gh repo list --json nameWithOwner,description,visibility,updatedAt --limit 30

# Filter by visibility
gh repo list --visibility public --json nameWithOwner,description
gh repo list --visibility private --json nameWithOwner,description

# Filter by language
gh repo list --language go --json nameWithOwner,description

# An org's repos
gh repo list my-org --json nameWithOwner,description,visibility --limit 50

# Source repos only (not forks)
gh repo list --source --json nameWithOwner,description

# Forks only
gh repo list --fork --json nameWithOwner,description

# Archived repos
gh repo list --archived --json nameWithOwner,description
```

### Create a Repository

```bash
# Public repo
gh repo create my-project --public --description "A new project" --clone

# Private repo
gh repo create my-project --private --description "Internal tool" --clone

# Create from template
gh repo create my-app --template owner/template-repo --public --clone

# Create in an org
gh repo create my-org/service-name --private --description "Microservice" --clone

# Create with .gitignore and license
gh repo create my-project \
  --public \
  --description "My project" \
  --gitignore Node \
  --license MIT \
  --clone

# Create without cloning
gh repo create my-project --public --description "Remote only"

# Create from existing local repo
cd my-local-project
gh repo create --source . --public --push
```

### Clone a Repository

```bash
# Clone via HTTPS (default)
gh repo clone owner/repo

# Clone into specific directory
gh repo clone owner/repo ./my-local-name

# Clone with SSH
gh repo clone owner/repo -- --config core.sshCommand="ssh -i ~/.ssh/my_key"

# Shallow clone
gh repo clone owner/repo -- --depth 1
```

### Fork a Repository

```bash
# Fork and clone
gh repo fork owner/repo --clone

# Fork without cloning
gh repo fork owner/repo

# Fork to an org
gh repo fork owner/repo --org my-org

# Fork with custom name
gh repo fork owner/repo --fork-name my-custom-name
```

### Edit Repository Settings

```bash
# Update description
gh repo edit --description "Updated project description"

# Update homepage
gh repo edit --homepage "https://myproject.dev"

# Change visibility
gh repo edit --visibility public
gh repo edit --visibility private

# Set default branch
gh repo edit --default-branch develop

# Enable/disable features
gh repo edit --enable-issues
gh repo edit --enable-issues=false
gh repo edit --enable-wiki
gh repo edit --enable-wiki=false
gh repo edit --enable-projects
gh repo edit --enable-projects=false

# Enable/disable merge strategies
gh repo edit --enable-merge-commit
gh repo edit --enable-squash-merge
gh repo edit --enable-rebase-merge
gh repo edit --enable-merge-commit=false

# Enable auto-merge
gh repo edit --enable-auto-merge

# Delete branch on merge
gh repo edit --delete-branch-on-merge

# Set topics
gh repo edit --add-topic "cli,golang,tool"
gh repo edit --remove-topic "old-topic"

# Multiple settings at once
gh repo edit \
  --description "Production API service" \
  --enable-squash-merge \
  --enable-merge-commit=false \
  --delete-branch-on-merge \
  --enable-auto-merge

# Edit a specific repo
gh repo edit owner/repo --description "New description"
```

### Archive / Unarchive

```bash
# Archive (makes repo read-only)
gh repo archive owner/repo

# Unarchive
gh repo unarchive owner/repo
```

### Delete a Repository

```bash
# Delete (requires confirmation or --yes flag)
gh repo delete owner/repo --yes
```

> **Warning**: This is irreversible. Requires the `delete_repo` scope: `gh auth refresh -s delete_repo`

### Rename a Repository

```bash
gh repo rename new-name
gh repo rename new-name -R owner/old-name
```

### Sync a Fork

```bash
# Sync fork's default branch with upstream
gh repo sync

# Sync a specific branch
gh repo sync --branch develop

# Sync without local changes (remote only)
gh repo sync owner/my-fork
```

### Deploy Keys

```bash
# List deploy keys
gh repo deploy-key list

# Add a deploy key
gh repo deploy-key add ~/.ssh/deploy.pub --title "CI server"

# Add with write access
gh repo deploy-key add ~/.ssh/deploy.pub --title "CI deploy" --allow-write

# Delete a deploy key
gh repo deploy-key delete <key-id>
```

## Managing Collaborators & Teams

These operations require `gh api`:

```bash
# List collaborators
gh api repos/owner/repo/collaborators --jq '.[].login'

# Add a collaborator
gh api repos/owner/repo/collaborators/username -X PUT -f permission=push

# Remove a collaborator
gh api repos/owner/repo/collaborators/username -X DELETE

# List teams with access (org repos)
gh api repos/owner/repo/teams --jq '.[] | "\(.slug): \(.permission)"'
```

## Branch Protection (via API)

```bash
# View branch protection rules
gh api repos/owner/repo/branches/main/protection --jq '{
  required_reviews: .required_pull_request_reviews.required_approving_review_count,
  dismiss_stale: .required_pull_request_reviews.dismiss_stale_reviews,
  require_ci: .required_status_checks.strict,
  contexts: .required_status_checks.contexts
}'

# Set branch protection
gh api repos/owner/repo/branches/main/protection -X PUT \
  -F "required_pull_request_reviews[required_approving_review_count]=1" \
  -F "required_pull_request_reviews[dismiss_stale_reviews]=true" \
  -F "required_status_checks[strict]=true" \
  -F "required_status_checks[contexts][]=ci/test" \
  -F "enforce_admins=true" \
  -F "restrictions=null"
```

## Secrets Management

```bash
# List secrets
gh secret list
gh secret list --org my-org

# Set a secret
gh secret set API_KEY --body "sk-abc123"

# Set from file
gh secret set PRIVATE_KEY < ./key.pem

# Set for specific environments
gh secret set DB_PASSWORD --env production --body "secret123"

# Delete a secret
gh secret delete API_KEY

# List variables (non-secret config)
gh variable list

# Set a variable
gh variable set DEPLOY_ENV --body "staging"
```

## Workflows

### New Project Setup

```bash
# 1. Create the repo
gh repo create my-org/new-service \
  --private \
  --description "User notification service" \
  --license MIT \
  --gitignore Node \
  --clone

# 2. Configure settings
cd new-service
gh repo edit \
  --enable-squash-merge \
  --enable-merge-commit=false \
  --enable-rebase-merge=false \
  --delete-branch-on-merge \
  --enable-auto-merge

# 3. Add topics
gh repo edit --add-topic "typescript,microservice,notifications"

# 4. Set up secrets for CI
gh secret set NPM_TOKEN --body "$NPM_TOKEN"
```

### Fork & Contribute Workflow

```bash
# 1. Fork and clone
gh repo fork owner/project --clone
cd project

# 2. Create feature branch
git checkout -b fix/typo-in-docs

# 3. Make changes and push
git add . && git commit -m "fix: correct typo in README"
git push -u origin fix/typo-in-docs

# 4. Create PR to upstream
gh pr create \
  --title "fix: correct typo in README" \
  --body "Fixed a small typo in the installation section."

# 5. Later, sync fork with upstream
gh repo sync
```

### Audit Repo Settings

```bash
# Check key settings
gh repo view --json nameWithOwner,visibility,defaultBranchRef,hasIssuesEnabled,hasWikiEnabled,hasProjectsEnabled,mergeCommitAllowed,squashMergeAllowed,rebaseMergeAllowed,deleteBranchOnMerge,autoMergeAllowed

# Check branch protection
gh api repos/owner/repo/branches/main/protection 2>/dev/null && echo "Protected" || echo "Not protected"
```

## Available JSON Fields

Use these with `--json` on `gh repo view`:

`assignableUsers`, `codeOfConduct`, `contactLinks`, `createdAt`, `defaultBranchRef`, `deleteBranchOnMerge`, `description`, `diskUsage`, `forkCount`, `fundingLinks`, `hasDiscussionsEnabled`, `hasIssuesEnabled`, `hasProjectsEnabled`, `hasWikiEnabled`, `homepageUrl`, `id`, `isArchived`, `isBlankIssuesEnabled`, `isEmpty`, `isFork`, `isInOrganization`, `isMirror`, `isPrivate`, `isSecurityPolicyEnabled`, `isTemplate`, `isUserConfigurationRepository`, `issueTemplates`, `labels`, `languages`, `latestRelease`, `licenseInfo`, `mergeCommitAllowed`, `milestones`, `mirrorUrl`, `name`, `nameWithOwner`, `openGraphImageUrl`, `owner`, `parent`, `primaryLanguage`, `pullRequestTemplates`, `pushedAt`, `rebaseMergeAllowed`, `repositoryTopics`, `securityPolicyUrl`, `squashMergeAllowed`, `sshUrl`, `stargazerCount`, `templateRepository`, `updatedAt`, `url`, `visibility`, `watchers`

## Tips

- Use `--clone` with `gh repo create` and `gh repo fork` to immediately start working locally.
- `gh repo edit` is powerful for enforcing team conventions across repos (merge strategies, auto-delete branches).
- For org-wide settings and bulk operations, loop over `gh repo list my-org --json nameWithOwner --jq '.[].nameWithOwner'`.
- `gh repo sync` keeps forks up-to-date without manual remote management.
- Use `gh secret set` in CI setup scripts to avoid manual secret configuration in the GitHub UI.
- Deleting repos requires the `delete_repo` token scope — re-auth with `gh auth refresh -s delete_repo` if needed.