GitHub Project Skill

Overview

GitHub repository setup, configuration, troubleshooting, and best practices for collaboration workflows.

When to Use

• PR won't merge or shows BLOCKED status
• Auto-merge not working for Dependabot/Renovate PRs
• Solo maintainer needs auto-approve for their own PRs
• Branch protection or ruleset configuration needed
• GitHub Actions workflow problems or CI failures
• Setting up CODEOWNERS, issue templates, or PR templates
• Repository standards compliance (TYPO3, Go, polyglot)

Quick Diagnostics

PR Won't Merge

# Check merge state, review decision, and unresolved threads
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:50){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

Solo maintainer projects MUST have auto-approve. Use assets/pr-quality.yml.template and keep required_approving_review_count >= 1. See references/auto-merge-guide.md for full setup.

Auto-merge Not Working

# Check who enabled auto-merge and bypass apps
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

Running Scripts

Verify repository configuration against best practices:

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

References

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