mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
12 KiB
12 KiB
name, description
| name | description |
|---|---|
| collaboration-github-repository-management | Repository creation, configuration, branch protection, tags, releases, and GitHub CLI operations |
GitHub Repository Management
Scope: Repository creation and configuration, branch management, branch protection rules, tags and releases, GitHub CLI operations, repository settings and templates
Lines: ~280
Last Updated: 2025-10-25
Format Version: 1.0 (Atomic)
When to Use This Skill
Activate this skill when:
- Creating and configuring new GitHub repositories
- Setting up branch protection rules and required reviews
- Managing releases with semantic versioning and release notes
- Using GitHub CLI for repository operations
- Configuring repository settings: webhooks, secrets, environments
- Creating repository, issue, and PR templates
- Setting default branches and branch naming conventions
- Generating changelogs and managing tags
Core Concepts
Repository Structure
Key components:
- Default branch: Main development branch (main or master)
- Protected branches: Branches with enforcement rules
- Environments: Deployment targets with secrets and protection rules
- Webhooks: HTTP callbacks for repository events
- Secrets: Encrypted environment variables
- Templates: Standardized issue and PR formats
# Repository hierarchy
repository/
├── .github/
│ ├── workflows/ # GitHub Actions
│ ├── ISSUE_TEMPLATE/ # Issue templates
│ ├── PULL_REQUEST_TEMPLATE.md
│ └── dependabot.yml
├── src/ # Source code
├── README.md
├── LICENSE
└── SECURITY.md
Branch Protection
Protection rules enforce:
- Required status checks before merging
- Required reviews (count and approval)
- Dismissal of stale reviews
- Required linear history
- Signed commits
- Administrator enforcement
GitHub CLI Workflow
# Authentication flow
gh auth login
gh auth status
# Repository operations
gh repo create → gh repo view → gh repo edit
↓
Branch protection → PR workflow → Release
↓
Cleanup and archival
Patterns
Creating Repositories with GitHub CLI
# Create new repository (interactive)
gh repo create my-project
# Create with flags
gh repo create my-project \
--public \
--description "Project description" \
--gitignore Node \
--license MIT
# Create from template
gh repo create my-project \
--template owner/template-repo \
--private
# Create and clone
gh repo create my-project --clone
# Initialize existing directory
cd existing-project
gh repo create --source=. --remote=origin --push
Repository Configuration
# View repository details
gh repo view owner/repo
# Edit repository settings
gh repo edit owner/repo \
--description "New description" \
--homepage "https://example.com" \
--default-branch main \
--enable-issues=true \
--enable-wiki=false
# Archive repository
gh repo archive owner/repo
# Delete repository (careful!)
gh repo delete owner/repo --confirm
Branch Protection Rules
Via GitHub CLI:
# Enable branch protection (requires API)
gh api repos/owner/repo/branches/main/protection \
--method PUT \
--field required_status_checks='{"strict":true,"contexts":["ci/build","ci/test"]}' \
--field enforce_admins=true \
--field required_pull_request_reviews='{"required_approving_review_count":2}' \
--field restrictions=null
Via Web UI (recommended for complex rules):
- Settings → Branches → Add rule
- Configure:
- Require pull request before merging
- Require approvals: 1-6 reviewers
- Dismiss stale reviews when new commits pushed
- Require review from Code Owners
- Require status checks to pass
- Require conversation resolution
- Require signed commits
- Require linear history
Protection rule pattern:
# Common protection for main branch
Branch pattern: main
✅ Require pull request reviews (2 approvals)
✅ Dismiss stale reviews
✅ Require review from Code Owners
✅ Require status checks (ci/build, ci/test)
✅ Require branches to be up to date
✅ Require conversation resolution
✅ Include administrators
Tags and Releases
Creating tags:
# Create annotated tag (recommended)
git tag -a v1.0.0 -m "Release version 1.0.0"
git push origin v1.0.0
# Create lightweight tag
git tag v1.0.0
git push origin v1.0.0
# List tags
git tag -l
# Delete tag
git tag -d v1.0.0
git push origin :refs/tags/v1.0.0
Semantic versioning:
MAJOR.MINOR.PATCH (1.2.3)
MAJOR: Breaking changes (1.x.x → 2.0.0)
MINOR: New features, backward compatible (1.2.x → 1.3.0)
PATCH: Bug fixes, backward compatible (1.2.3 → 1.2.4)
Pre-release: 1.0.0-alpha.1, 1.0.0-beta.2, 1.0.0-rc.1
Creating releases with GitHub CLI:
# Create release from tag
gh release create v1.0.0 \
--title "Version 1.0.0" \
--notes "Release notes here"
# Create release with assets
gh release create v1.0.0 \
--title "Version 1.0.0" \
--notes-file CHANGELOG.md \
dist/*.tar.gz dist/*.zip
# Create draft release
gh release create v1.0.0 \
--draft \
--title "Version 1.0.0" \
--notes "Draft release"
# Generate release notes automatically
gh release create v1.0.0 --generate-notes
# List releases
gh release list
# View specific release
gh release view v1.0.0
# Download release assets
gh release download v1.0.0
Repository Templates
Issue template (.github/ISSUE_TEMPLATE/bug_report.md):
---
name: Bug Report
about: Report a bug to help us improve
title: '[BUG] '
labels: bug
assignees: ''
---
## Bug Description
A clear description of the bug.
## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error
## Expected Behavior
What should happen.
## Actual Behavior
What actually happens.
## Environment
- OS: [e.g., macOS 14.0]
- Browser: [e.g., Chrome 120]
- Version: [e.g., 1.2.3]
## Additional Context
Screenshots, logs, or other context.
Pull request template (.github/PULL_REQUEST_TEMPLATE.md):
## Summary
Brief description of changes.
## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update
## Testing
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed
## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex logic
- [ ] Documentation updated
- [ ] No new warnings generated
## Related Issues
Closes #123
Related to #456
Repository Secrets and Environments
Managing secrets with GitHub CLI:
# Set repository secret
gh secret set API_KEY < api_key.txt
# Set secret with value
echo "secret-value" | gh secret set SECRET_NAME
# List secrets
gh secret list
# Delete secret
gh secret delete SECRET_NAME
# Set environment secret
gh secret set API_KEY --env production
Configuring environments (via Web UI):
- Settings → Environments → New environment
- Configure:
- Environment protection rules
- Required reviewers before deployment
- Wait timer (delay before deployment)
- Environment secrets
- Deployment branches (limit to specific branches)
Webhooks Configuration
# Create webhook via API
gh api repos/owner/repo/hooks \
--method POST \
--field name=web \
--field config[url]=https://example.com/webhook \
--field config[content_type]=json \
--field events[]="push" \
--field events[]="pull_request"
# List webhooks
gh api repos/owner/repo/hooks
# Delete webhook
gh api repos/owner/repo/hooks/123 --method DELETE
Quick Reference
GitHub CLI Commands
# Authentication
gh auth login # Authenticate with GitHub
gh auth status # Check authentication status
gh auth logout # Log out
# Repository operations
gh repo create [name] # Create repository
gh repo clone owner/repo # Clone repository
gh repo view [owner/repo] # View repository details
gh repo edit [owner/repo] # Edit repository settings
gh repo fork owner/repo # Fork repository
gh repo sync owner/repo # Sync fork with upstream
# Release management
gh release create <tag> # Create release
gh release list # List releases
gh release view <tag> # View release details
gh release download <tag> # Download release assets
gh release delete <tag> # Delete release
# Secret management
gh secret set <name> # Set secret
gh secret list # List secrets
gh secret delete <name> # Delete secret
Semantic Versioning Quick Guide
Version format: MAJOR.MINOR.PATCH
Breaking change: 1.0.0 → 2.0.0
New feature: 1.2.0 → 1.3.0
Bug fix: 1.2.3 → 1.2.4
Pre-release tags:
- alpha: 1.0.0-alpha.1
- beta: 1.0.0-beta.1
- rc: 1.0.0-rc.1
Branch Protection Checklist
✅ DO: Protect main/production branches
✅ DO: Require 1-2 approvals for PRs
✅ DO: Require status checks to pass
✅ DO: Dismiss stale reviews on new commits
✅ DO: Require conversation resolution
✅ DO: Require linear history for clean git log
❌ DON'T: Allow direct pushes to protected branches
❌ DON'T: Skip status checks for administrators (unless necessary)
❌ DON'T: Allow force pushes to protected branches
Anti-Patterns
❌ No Branch Protection
# WRONG: Allow direct pushes to main
# Anyone can push without review
git push origin main
Problems:
- No code review process
- Untested code reaches production
- No audit trail
# CORRECT: Require PRs and reviews
# Settings → Branches → Add rule for main
# ✅ Require pull request reviews (2 approvals)
# ✅ Require status checks
❌ Hardcoded Secrets in Repository
# WRONG: Secrets in workflow file
env:
API_KEY: "sk-abc123xyz"
DATABASE_PASSWORD: "password123"
Problems:
- Secrets visible in git history
- Security breach risk
- Difficult to rotate credentials
# CORRECT: Use GitHub Secrets
env:
API_KEY: ${{ secrets.API_KEY }}
DATABASE_PASSWORD: ${{ secrets.DATABASE_PASSWORD }}
# Set via CLI
gh secret set API_KEY < api_key.txt
❌ No Release Process
# WRONG: Push tags without documentation
git tag v1.0.0 && git push origin v1.0.0
# No release notes, no changelog
Problems:
- Users don't know what changed
- No downloadable assets
- Difficult to track versions
# CORRECT: Create proper releases
gh release create v1.0.0 \
--title "Version 1.0.0" \
--notes-file CHANGELOG.md \
dist/*.tar.gz
# Include:
# - Version number (semantic versioning)
# - Release notes (what changed)
# - Downloadable assets (binaries, archives)
❌ Missing Templates
Problems:
- Inconsistent issue reports
- Missing information in PRs
- Wasted time asking for details
# CORRECT: Create templates
mkdir -p .github/ISSUE_TEMPLATE
# Add bug report template
# Add feature request template
# Add pull request template
# Commit templates
git add .github/
git commit -m "Add issue and PR templates"
❌ Default Branch Named 'master'
# WRONG: Using outdated default branch name
# main branch is called 'master'
# CORRECT: Use 'main' as default branch
# Rename existing repository
git branch -m master main
git push -u origin main
# Update default branch on GitHub
gh repo edit owner/repo --default-branch main
# Delete old remote branch
git push origin --delete master
Related Skills
collaboration/github/github-pull-requests.md- PR workflow and code review processcollaboration/github/github-actions-workflows.md- CI/CD automation with branch protectioncollaboration/github/github-security-features.md- Security settings and dependency managementcollaboration/github/github-issues-projects.md- Issue templates and project managementcicd/ci-security.md- Secret management best practicesversion-control/git-branching-strategies.md- Branch naming and workflow strategies
Last Updated: 2025-10-25
Format Version: 1.0 (Atomic)