| name | github-repo-management |
| description | Manage GitHub repositories end to end - issues, labels, pull request workflows, branch protection, semantic-version releases, GitHub Actions CI, and deployment to Vercel, Google Cloud Run, and AWS. Use when setting up or fixing CI workflows, writing issue or PR templates, cutting a release, configuring branch protection or CODEOWNERS, pinning or upgrading GitHub Actions, wiring keyless OIDC authentication from Actions to a cloud provider, or building a deploy pipeline. Do NOT use for decomposing work into milestone, umbrella, epic, or subtask hierarchies - see github-work-decomposition. Do NOT use for AWS-native CodePipeline, CodeBuild, or CodeDeploy orchestration - see the aws-deployment skill. |
GitHub Repository Management
Repository operations and deployment pipelines driven from GitHub. This file is the routing layer: read the reference file that matches the task rather than loading everything.
Scope boundary
| Concern | This skill | Elsewhere |
|---|
| Issues, labels, PR flow, releases, CI, branch protection | Yes | — |
| Deploying from GitHub Actions to Vercel / GCP / AWS | Yes | — |
| Milestone → umbrella → epic → subtask hierarchies | No | github-work-decomposition |
| AWS CodePipeline / CodeBuild / CodeDeploy orchestration | No | aws-deployment (AWS official) |
| Vercel dashboard config, domains, edge runtime tuning | No | Vercel docs / vercel-cli skill |
| Application code, tests, framework specifics | No | Language-specific skills |
Routing
| Task | Read |
|---|
Issue templates, label taxonomy, gh issue commands | references/issue-templates.md |
PR template, PR validation workflow, gh pr commands, merge strategy | references/pr-workflows.md |
SemVer, CHANGELOG, tag-triggered release workflow, gh release | references/release-management.md |
| CI workflow shape, matrix testing, caching, security scanning | references/ci-workflows.md |
| Branch protection, rulesets, CODEOWNERS, Dependabot, repo settings | references/repo-settings.md |
| OIDC setup, environments, secrets vs. vars, rollback discipline | references/deploy-common.md |
| Vercel deployment (Git integration and CLI paths) | references/deploy-vercel.md |
| Cloud Run / GKE / App Engine deployment via Workload Identity | references/deploy-gcp.md |
| ECS, Lambda, S3+CloudFront deployment via IAM role assumption | references/deploy-aws.md |
Architecture diagrams for all of the above: github-repo-management-diagrams.md.
Non-negotiables
- Never write a mutable action ref. No
@master, no @main, no bare @v4 for third-party actions. Pin to a full 40-character commit SHA with the version in a trailing comment. A mutable ref on a third-party action means whatever lands on their default branch executes in CI with the repository's GITHUB_TOKEN.
- Never store long-lived cloud credentials as repository secrets. Use OIDC (
id-token: write) for AWS and GCP. Vercel is the exception — it has no inbound OIDC and requires a token; scope it and store it at the environment level, not the repository level.
- Set
permissions: explicitly on every workflow. Start from contents: read and add only what each job needs. The default token is over-permissive.
- Never let a workflow triggered by
pull_request_target check out untrusted PR head code. That combination executes fork code with write-scoped secrets.
- Gate production deploys behind a GitHub Environment with required reviewers or a wait timer. The workflow file is not an access control boundary; the environment is.
- Verify pins before emitting them. Resolve tags to commit SHAs with
git ls-remote --tags REPO 'refs/tags/TAG^{}' — for annotated tags the plain tag ref points at a tag object, not a commit, and pinning that produces a workflow that fails to resolve.
Action pin registry
Verified 2026-08-12 via git ls-remote. Re-verify before reuse; treat any pin older than ~90 days as stale.
actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
actions/setup-node@820762786026740c76f36085b0efc47a31fe5020
actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9
softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228
ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38
aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25
aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c
google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093
google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db
google-github-actions/deploy-cloudrun@2028e2d7d30a78c6910e0632e48dd561b064884d
docker/login-action@dbcb813823bdd20940b903addbd779551569679f
docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a
github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3
Known-stale refs to reject on sight: actions/checkout@v4 (three majors behind), softprops/action-gh-release@v1 and @v2 (v2 line ended at v2.6.2 and is unmaintained on the deprecated Node 20 runtime), any @master or @main pin.
Refresh the whole table:
git ls-remote --tags https://github.com/OWNER/REPO "refs/tags/TAG^{}" | awk '{print $1}'
Deploy target selection
Pick the path before writing YAML. The wrong default here costs more than any other decision in this skill.
| Situation | Path |
|---|
| Vercel, standard app, no custom build steps | Git integration only — write no workflow. Pushing to a connected repo already triggers preview and production deploys. Adding a workflow on top produces double deploys and double billing. |
| Vercel, needs CI gates or monorepo build orchestration before deploy | CLI path: vercel pull → vercel build → vercel deploy --prebuilt, and disable the Git integration for that project |
| GCP container workload | Cloud Run via Workload Identity Federation + deploy-cloudrun |
| GCP static site or function | Cloud Storage / Cloud Functions via WIF + setup-gcloud |
| AWS, deploying from GitHub Actions | OIDC role assumption + service-specific action or CLI |
| AWS, deploying within AWS with CodePipeline | Out of scope — hand off to aws-deployment |
The most common mistake with Vercel is writing a workflow at all. Ask whether the Git integration is already connected before generating YAML.
Core workflow
1. Identify the concern → scope boundary table above
2. Load the matching reference → routing table above
3. If emitting workflow YAML:
a. Pull pins from the registry (verify freshness)
b. Set explicit `permissions:`
c. For deploys: confirm the Environment exists and is protected
4. Validate against the gates below
5. Report what was changed and what still needs a human (secrets, OIDC
trust policies, environment reviewers — none of which can be set from
a workflow file)
Validation gates
Run before handing back any workflow file:
Repository skeleton
.github/
├── ISSUE_TEMPLATE/
│ ├── bug_report.yml
│ ├── feature_request.yml
│ └── config.yml
├── workflows/
│ ├── ci.yml # push + PR: lint, test, scan
│ ├── pr-checks.yml # PR hygiene: title, size, conflicts
│ ├── release.yml # tag-triggered
│ └── deploy.yml # environment-gated
├── PULL_REQUEST_TEMPLATE.md
├── CODEOWNERS
└── dependabot.yml
CHANGELOG.md
Failure modes
| Symptom | Cause | Fix |
|---|
Unable to resolve action ... unable to find version on a SHA pin | Pinned the annotated tag object instead of the commit | Re-resolve with refs/tags/TAG^{} |
Deploy job fails with Credentials could not be loaded | Missing id-token: write in the job's permissions | Add it at job level; workflow-level alone is not inherited when a job overrides permissions |
AWS AssumeRoleWithWebIdentity denied | Trust policy sub condition does not match the actual claim | Print the claim; ref:refs/heads/main and environment:production are different subjects |
| Two deployments race, older one wins | No concurrency block | Add concurrency: {group: deploy-prod, cancel-in-progress: false} |
| Vercel deploys twice per push | Git integration and a CLI workflow both active | Disable one — see references/deploy-vercel.md |
| Release workflow cannot create a release | contents: write missing | Add to the release job only |
