github-repo-management

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

1. 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.
2. 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.
3. Set permissions: explicitly on every workflow. Start from contents: read and add only what each job needs. The default token is over-permissive.
4. Never let a workflow triggered by pull_request_target check out untrusted PR head code. That combination executes fork code with write-scoped secrets.
5. 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.
6. 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                    # v7.0.1
actions/setup-node@820762786026740c76f36085b0efc47a31fe5020                  # v7.0.0
actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a             # v7.0.1
actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9                       # v6.1.0
softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228         # v3.0.2
ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38           # 2.0.0
aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25           # v0.36.0
aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c  # v6.2.3
google-github-actions/auth@7c6bc770dae815cd3e89ee6cdf493a5fab2cc093          # v3.0.0
google-github-actions/setup-gcloud@aa5489c8933f4cc7a4f7d45035b3b1440c9c10db  # v3.0.1
google-github-actions/deploy-cloudrun@2028e2d7d30a78c6910e0632e48dd561b064884d  # v3.0.1
docker/login-action@dbcb813823bdd20940b903addbd779551569679f                 # v4.6.0
docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a            # v7.3.0
github/codeql-action/upload-sarif@5595ccaf912efad79be6eef63a5619ff05969be3   # v4.37.6

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:

• Every uses: is a 40-char SHA with a version comment — grep -nE 'uses:.*@(v[0-9]|master|main)$' .github/workflows/*.yml returns nothing
• Every job or workflow declares permissions:
• No pull_request_target job checks out github.event.pull_request.head.sha
• No cloud access keys in secrets.* — AWS and GCP jobs use id-token: write
• Production deploy jobs declare environment:
• Concurrency group set on deploy workflows so two pushes cannot race the same environment
• Third-party actions are pinned and the repository is one you would accept a dependency from
• actionlint passes if available

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