GitHub Project Skill Skill

GitHub Project Skill

GitHub repository configuration, troubleshooting, and collaboration workflow best practices.

When to Use

PR won't merge, BLOCKED, or unresolved threads
Auto-merge fails for Dependabot/Renovate
Solo maintainer needs auto-approve
Branch protection, rulesets, enforce_admins
GHA failures or permission issues
Signed commit merge (rebase can't auto-sign)
CodeQL default vs custom workflows
OpenSSF Scorecard (token perms, pinned deps)
CODEOWNERS, issue/PR templates, release labels
Fork PR merge base (too many commits)

Quick Diagnostics

PR Won't Merge

gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){
  repository(owner:$owner,name:$repo){pullRequest(number:$pr){
    mergeStateStatus reviewDecision mergeable
    reviewThreads(first:100){nodes{isResolved comments(first:1){nodes{body}}}}
  }}
}' -f owner=OWNER -f repo=REPO -F pr=NUMBER --jq '.data.repository.pullRequest'

Solo Maintainer: PRs Stuck on REVIEW_REQUIRED

Use assets/pr-quality.yml.template for auto-approve with required_approving_review_count >= 1.

Auto-merge Setup

Requirements: allow_auto_merge on repo, pull_request_target trigger (not pull_request), check user.login (not github.actor), gh pr merge --auto with dynamic strategy.

Auto-merge Not Working

gh api graphql -f query='query{repository(owner:"OWNER",name:"REPO"){
  pullRequest(number:PR){autoMergeRequest{enabledBy{login}}}
}}' --jq '.data.repository.pullRequest.autoMergeRequest'

gh api repos/OWNER/REPO/branches/main/protection/required_pull_request_reviews \
  --jq '.bypass_pull_request_allowances.apps[].slug'

GitHub Actions Failing

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 & Compliance Quick Checks

gh api repos/OWNER/REPO/branches/main/protection --jq '.enforce_admins.enabled'
gh api repos/OWNER/REPO/code-scanning/default-setup --jq '.state'
gh api graphql -f query='query($owner:String!,$repo:String!,$pr:Int!){
  repository(owner:$owner,name:$repo){pullRequest(number:$pr){
    reviewThreads(first:100){nodes{id isResolved}}
  }}
}' -f owner=OWNER -f repo=REPO -F pr=NUMBER

Merge Strategy Issues

See references/auto-merge-guide.md for: rebase-merge-with-signed-commits fixes, workflow-file PR manual merges, and the Copilot-review auto-approve race.

Running Scripts

scripts/verify-github-project.sh /path/to/repository

References

| Topic | Reference | |-------|-----------| | Repository file layout | references/repository-structure.md | | Branch migration (master to main) | references/branch-migration.md | | Dependabot/Renovate configuration | references/dependency-management.md | | Auto-approve + auto-merge | references/auto-merge-guide.md | | Merge strategy for signed commits | references/merge-strategy.md | | Sub-issues and issue hierarchy | references/sub-issues.md | | Release labeling automation | references/release-labeling.md | | gh CLI commands | references/gh-cli-reference.md | | Go, TYPO3, polyglot CI checklists | references/repo-setup-guide.md | | OpenSSF Scorecard, CodeQL, security | references/security-config.md | | Workflow linting (actionlint) | references/actionlint-guide.md | | Bash pitfalls in workflow run: steps | references/workflow-bash-patterns.md | | PR shows too many commits (fork merge base) | references/pr-commit-cleanup.md | | Multi-repo batch ops | references/multi-repo-operations.md | | Reusable workflow supply-chain trust + SHA pinning | references/reusable-workflow-security.md | | Reusable workflow pitfalls (composite actions, ref caching, permissions) | references/reusable-workflow-pitfalls.md | | Org-level security settings (SHA pinning) | references/org-security-settings.md | | Tag validation (defense-in-depth) | references/tag-validation.md | | AI reviewer pushback patterns | references/ai-reviewer-pushback.md | | Agentic workflows | references/agentic-workflows.md |

Contributing: https://github.com/netresearch/github-project-skill

Agent Skills: GitHub Project Skill

Install this agent skill to your local

Skill Files