github-project

# GitHub Project Skill ## When to Use - **Post `gh repo create` + push, before first PR** — REQUIRED: `scripts/init-branch-protection.sh OWNER/REPO` - **First issue/PR into a foreign repo** — `references/upstream-contributions.md` BEFORE filing - Adding a workflow job — pitfall #6 - PR won't merge / threads - Auto-merge fails (Dependabot/Renovate) - Solo auto-approve - Branch protection, rulesets - GHA failures - Signed-commit merge - CodeQL - Scorecard - CODEOWNERS, templates, labels - Fork PR merge base ## Quick Diagnostics ### PR Won't Merge ```bash gh pr view PR --repo OWNER/REPO \ --json mergeStateStatus,reviewDecision,mergeable,reviewThreads ``` ### Solo Maintainer: Stuck on REVIEW_REQUIRED Either `assets/pr-quality.yml.template` (auto-approve, `required_approving_review_count >= 1`) or `scripts/init-branch-protection.sh OWNER/REPO --solo` (approvals 0, conversation resolution kept) — `references/auto-merge-guide.md` compares both. ### Auto-merge Setup Requires `allow_auto_merge`, `pull_request_target`, bot detection, `gh pr merge --auto` (`references/auto-merge-guide.md`). ### Auto-merge Not Working ```bash gh pr view PR --repo OWNER/REPO --json autoMergeRequest --jq .autoMergeRequest ``` Bypass actors: `references/security-config.md`. ### GitHub Actions Failing ```bash gh run list --repo OWNER/REPO --limit 5 gh run view RUN_ID --repo OWNER/REPO --log-failed gh run rerun RUN_ID --repo OWNER/REPO ``` ### Security Quick Checks ```bash gh api repos/OWNER/REPO/rules/branches/main gh api repos/OWNER/REPO/branches/main/protection \ --jq '{rcr: .required_conversation_resolution.enabled, admins: .enforce_admins.enabled}' gh api repos/OWNER/REPO/code-scanning/default-setup --jq '.state' gh pr view PR --repo OWNER/REPO --json reviewThreads --jq '.reviewThreads' ``` ### Merge Strategy Issues `references/auto-merge-guide.md`: signed-commit rebase, workflow-file PRs, Copilot race. ### Calling Organisation Reusables **Rule:** `uses: netresearch/<repo>/.github/workflows/<name>.yml@main`. Never a commit hash, also not `@<sha> # main`; third-party actions stay SHA-pinned. A CodeQL `actions/unpinned-tag`, zizmor or SonarCloud finding on such a line is dismissed as won't fix, never fixed by pinning. Why: `references/reusable-workflow-security.md`. ## Running Scripts ```bash scripts/init-branch-protection.sh OWNER/REPO # baseline scripts/init-branch-protection.sh OWNER/REPO --from-current-checks # after first CI scripts/init-branch-protection.sh OWNER/REPO --merge-queue # then: org-standard queue scripts/verify-github-project.sh /path/to/repository # local-checkout audit ``` ## No editorializing State what a change does, not how good it is. ## References | Topic | Reference | |-------|-----------| | Repo bootstrap | `references/repo-bootstrap.md` | | Repository file layout | `references/repository-structure.md` | | Branch migration | `references/branch-migration.md` | | Repository retirement, Packagist abandon | `references/repo-retirement.md` | | Dependabot/Renovate | `references/dependency-management.md` | | Auto-approve + auto-merge | `references/auto-merge-guide.md` | | Merge strategy | `references/merge-strategy.md` | | Sub-issues | `references/sub-issues.md` | | Release labeling | `references/release-labeling.md` | | gh CLI commands | `references/gh-cli-reference.md` | | Polyglot CI checklists | `references/repo-setup-guide.md` | | Scorecard, CodeQL, security | `references/security-config.md` | | actionlint | `references/actionlint-guide.md` | | Actions upgrades, Node-runtime wave | `references/actions-upgrade-guide.md` | | Workflow bash pitfalls | `references/workflow-bash-patterns.md` | | Runner capacity, concurrency groups (schedule vs push) | `references/ci-runner-capacity.md` | | No editorializing | `references/no-editorializing.md` | | Fork merge base | `references/pr-commit-cleanup.md` | | Multi-repo batch ops | `references/multi-repo-operations.md` | | Private copy of a public repo (mirror push) | `references/multi-repo-operations.md` | | Cross-repo references, code permalinks | `references/cross-repo-references.md` | | Foreign-repo contributions | `references/upstream-contributions.md` | | Reusable workflow security | `references/reusable-workflow-security.md` | | Reusable workflow pitfalls | `references/reusable-workflow-pitfalls.md` | | Org security settings | `references/org-security-settings.md` | | Tag validation | `references/tag-validation.md` | | AI reviewer pushback | `references/ai-reviewer-pushback.md` | | Agentic workflows | `references/agentic-workflows.md` | | Pages + data collectors | `references/pages-and-collector-workflows.md` | --- > Contributing: https://github.com/netresearch/github-project-skill