What should I do when a PR won't merge?

Use the quick diagnostics to inspect mergeStateStatus, reviewDecision, and unresolved threads, then address conflicts or review blockers.

How do I enable auto-merge for Dependabot/Renovate PRs?

Check who enabled auto-merge and bypass apps, configure the correct auto-merge setup per the auto-merge guide, and reference the relevant docs in references/auto-merge-guide.md.

How do I set up CODEOWNERS and templates?

Add a CODEOWNERS file, create issue and PR templates, and align with branch protections and repository standards (TYPO3, Go, polyglot).

github-project

npx machina-cli add skill netresearch/github-project-skill/github-project --openclaw

Files (1)

SKILL.md

3.1 KB

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

Topic	Reference
Repository file layout and conventions	`references/repository-structure.md`
Branch migration (master to main)	`references/branch-migration.md`
Dependabot/Renovate configuration	`references/dependency-management.md`
Auto-approve + auto-merge (solo maintainer, bots)	`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`
PR shows too many commits (fork merge base)	`references/pr-commit-cleanup.md`

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

Source

git clone https://github.com/netresearch/github-project-skill/blob/main/skills/github-project/SKILL.mdView on GitHub

Overview

GitHub Project Skill guides repository setup, configuration, and problem-solving for collaboration workflows. It covers PR blockers, branch protection, CODEOWNERS, templates, and Actions, helping teams ship faster.

How This Skill Works

It uses quick diagnostics and GraphQL/API checks to surface PR states, reviews, and protections. It then guides configuration changes (branch protection, CODEOWNERS, templates) and reruns validations to ensure healthy collaboration workflows.

When to Use It

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

Quick Start

Step 1: Run the quick diagnostics to inspect PR state (mergeStateStatus, review decisions, unresolved threads)
Step 2: If needed, adjust auto-merge or solo-maintainer auto-approve using assets/pr-quality.yml.template and references/auto-merge-guide.md, and configure branch protections as required
Step 3: Verify repository against best practices by running scripts/verify-github-project.sh /path/to/repository

Best Practices

For solo maintainers, enforce auto-approve by keeping required_approving_review_count >= 1 and using assets/pr-quality.yml.template
Configure CODEOWNERS, issue templates, and PR templates early to standardize reviews
Review and tune branch protection and bypass rules for trusted apps and auto-merge flows
Enable Dependabot/Renovate auto-merge and connect configurations to references/auto-merge-guide.md
Validate repository compliance against best practices by running scripts/verify-github-project.sh /path/to/repository

Example Use Cases

A blocked PR is diagnosed by inspecting mergeStateStatus and review decisions to identify blockers
Dependabot PRs fail auto-merge and are resolved by enabling auto-merge and checking bypass apps
A solo maintainer's PR is auto-approved by configuring required_approving_review_count and auto-merge settings
CODEOWNERS and PR templates are added to a repo with TYPO3, Go, and polyglot stacks to standardize ownership
GitHub Actions failures are investigated by listing recent runs and re-running failed workflows

Frequently Asked Questions

Add this skill to your agents