GitHub Project Skill

May 23, 2026 · View on GitHub

GitHub platform configuration and repository management patterns. This skill focuses exclusively on GitHub-specific features.

New repo? Run this BEFORE the first PR: bash skills/github-project/scripts/init-branch-protection.sh OWNER/REPO Applies required_conversation_resolution: true + 1-approver baseline so the "abort merge if unresolved threads" rule is structurally enforced, not just documented. See skills/github-project/SKILL.md → Required First Step After gh repo create for the two-step flow.

🔌 Compatibility

This is an Agent Skill following the open standard originally developed by Anthropic and released for cross-platform use.

Supported Platforms:

  • ✅ Claude Code (Anthropic)
  • ✅ Cursor
  • ✅ GitHub Copilot
  • ✅ Other skills-compatible AI agents

Skills are portable packages of procedural knowledge that work across any AI agent supporting the Agent Skills specification.

Scope Boundaries

This Skill Covers:

  • Branch protection rules and PR workflows
  • CODEOWNERS configuration
  • GitHub Issues, Discussions, Projects
  • Sub-issues and issue hierarchies (parent/child relationships)
  • Dependabot/Renovate auto-merge
  • GitHub Releases configuration
  • Repository collaboration features

Delegate to Other Skills:

  • CI/CD pipelines → go-development, php-modernization, typo3-testing
  • Security scanning (CodeQL, gosec) → security-audit
  • SLSA, SBOMs, supply chain → enterprise-readiness
  • Git branching strategies, conventional commits → git-workflow

Triggers

Setup & Configuration:

  • Creating a new GitHub repository
  • "Check my GitHub project setup"
  • "Configure branch protection"
  • "Set up GitHub Issues/Discussions"
  • "How do I require PR reviews?"
  • "Auto-merge Dependabot PRs"
  • "Configure CODEOWNERS"

Sub-Issues & Issue Hierarchies:

  • "Create sub-issues"
  • "Add child issues to parent"
  • "Link issues as parent/child"
  • "Break down issue into sub-tasks"
  • "Set up issue hierarchy"
  • "Convert checklist to sub-issues"

Troubleshooting (PR Merge Blocked):

  • "PR can't be merged" / "merge is blocked"
  • "unresolved conversations" / "unresolved comments"
  • "required reviews not met"
  • "CODEOWNERS review required"
  • "status checks failed" (for branch protection context)
  • gh pr merge returns error

Troubleshooting (Auto-Merge Failures):

  • "auto-merge not working" / "Dependabot PR not merging"
  • "Merge method squash merging is not allowed"
  • "Merge method merge commit is not allowed"
  • "required status check not found"
  • "status check name mismatch"
  • PRs stuck with auto-merge enabled
  • "Protected branch rules not configured" (--auto requires branch protection)
  • Merge queue not processing PRs

Troubleshooting (Ruleset Conflicts):

  • "Rebase is not an allowed merge method"
  • "Squash is not an allowed merge method"
  • "Merge commit is not an allowed merge method"
  • Ruleset merge method mismatch warning on PR

Merge Queue Configuration:

  • "set up merge queue"
  • "enqueuePullRequest"
  • "auto-merge with merge queue"
  • "GraphQL merge queue mutation"

Branch Migration:

  • "rename master to main"
  • "change default branch"
  • "migrate from master"
  • "prevent master branch"
  • "block master from being created"

Installation

Add the Netresearch marketplace once, then browse and install skills:

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace

npx (skills.sh)

Install with any Agent Skills-compatible agent:

npx skills add https://github.com/netresearch/github-project-skill --skill github-project

Download Release

Download the latest release and extract to your agent's skills directory.

Git Clone

git clone https://github.com/netresearch/github-project-skill.git

Composer (PHP Projects)

composer require netresearch/github-project-skill

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

npm install --save-dev \
  @netresearch/agent-skill-coordinator \
  github:netresearch/github-project-skill

Requires @netresearch/agent-skill-coordinator, which discovers the skill in node_modules and registers it in AGENTS.md via a postinstall hook. For pnpm, also allowlist the coordinator's postinstall:

{
  "pnpm": {
    "onlyBuiltDependencies": ["@netresearch/agent-skill-coordinator"]
  }
}

Workflows

New Repository Setup

To set up a new GitHub repository:

  1. Create essential files: README.md, LICENSE, SECURITY.md
  2. Configure .github/ directory structure (see references/repository-structure.md)
  3. Set up branch protection on main branch
  4. Configure CODEOWNERS for automatic reviewer assignment
  5. Create issue and PR templates
  6. Enable Dependabot or Renovate for dependency updates
  7. Configure auto-merge workflow for dependency PRs
  8. Set up release notes configuration

Run verification: ./scripts/verify-github-project.sh /path/to/repo

Branch Configuration

Required branch settings:

SettingValueRationale
Default branch namemainIndustry standard
Default branch protected✅Prevent direct pushes
Allowed merge methodMerge commits onlyPreserve complete history
Delete branch on merge✅Keep repo clean

To configure via GitHub CLI:

# Ensure default branch is named "main"
gh api repos/{owner}/{repo} --jq '.default_branch'

# Configure merge settings (merge commits only, delete on merge)
gh repo edit --enable-merge-commit --disable-rebase-merge --disable-squash-merge --delete-branch-on-merge

Note: If you prefer rebase merging for linear history, use --enable-rebase-merge --disable-merge-commit instead. Ensure consistency with any GitHub Rulesets (see Rulesets Configuration).

Repository Settings

Complete repository settings:

SettingValueRationale
Allow merge commits✅With PR title and description
Allow squash merging❌Preserve commit granularity
Allow rebase merging❌Use merge queue instead
Automatically delete head branches✅Keep repo clean
Allow auto-merge✅Enable merge queue integration
Always suggest updating PR branches✅Keep PRs up-to-date with base
Discussions✅Community Q&A
Wikis❌Use docs folder instead

Configure via CLI:

# Configure all repository settings
gh repo edit \
  --enable-merge-commit \
  --disable-squash-merge \
  --disable-rebase-merge \
  --delete-branch-on-merge \
  --enable-auto-merge \
  --enable-discussions \
  --disable-wiki

# Set merge commit message format (PR title and description)
gh api repos/{owner}/{repo} \
  --method PATCH \
  -f merge_commit_title=PR_TITLE \
  -f merge_commit_message=PR_BODY

# Enable "always suggest updating PR branches"
gh api repos/{owner}/{repo} \
  --method PATCH \
  -F allow_update_branch=true

Important: Do NOT enable required_linear_history when using merge commits. Linear history requires fast-forward merges only (no merge commits). If you see "not authorized to push" errors, check if required_linear_history is enabled and disable it.

Renaming "master" to "main"

For complete migration steps from master to main as default branch, see references/branch-migration.md.

Quick start:

git branch -m master main
git push -u origin main
gh repo edit --default-branch main
git push origin --delete master

Branch Protection Configuration

To configure branch protection via GitHub CLI:

# View current protection
gh api repos/{owner}/{repo}/branches/main/protection

# Set branch protection
gh api repos/{owner}/{repo}/branches/main/protection \
  --method PUT \
  -f required_status_checks='{"strict":true,"contexts":["test","lint"]}' \
  -f enforce_admins=true \
  -f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true,"require_code_owner_reviews":true}' \
  -f restrictions=null \
  -f required_conversation_resolution=true

Recommended Settings:

SettingValuePurpose
Require pull request✅Enforce code review
Required approvals1+Based on team size
Dismiss stale reviews✅Re-review after changes
Require CODEOWNERS review✅Domain expert review
Require conversation resolution✅All comments addressed
Do not allow force pushes✅Protect history
Allow merge commits✅Preserve complete history
Disable rebase merge✅Avoid linear-only restriction
Disable squash merge✅Preserve commit granularity
Delete branch on merge✅Auto-cleanup merged branches

GitHub Rulesets Configuration

GitHub Rulesets provide repository rules that can override or conflict with repository-level settings. Critical: The pull_request rule in rulesets has its own allowed_merge_methods setting that must match repository settings.

View existing rulesets:

# List all rulesets
gh api repos/{owner}/{repo}/rulesets

# Get specific ruleset details
gh api repos/{owner}/{repo}/rulesets/{ruleset_id}

Common Issue: "Rebase is not an allowed merge method" Warning

This warning appears on PRs when there's a mismatch between:

  1. Repository settings (allow_rebase_merge: false)
  2. Ruleset settings (allowed_merge_methods includes "rebase")

Diagnosis:

# Check repository merge settings
gh api repos/{owner}/{repo} --jq '{allow_merge_commit, allow_rebase_merge, allow_squash_merge}'

# Check ruleset merge settings
gh api repos/{owner}/{repo}/rulesets/{ruleset_id} --jq '.rules[] | select(.type == "pull_request") | .parameters.allowed_merge_methods'

# Check merge queue settings
gh api repos/{owner}/{repo}/rulesets/{ruleset_id} --jq '.rules[] | select(.type == "merge_queue") | .parameters.merge_method'

Fix: Update ruleset to match repository settings

For merge commits only:

gh api repos/{owner}/{repo}/rulesets/{ruleset_id} -X PUT --input - << 'EOF'
{
  "rules": [
    {
      "type": "pull_request",
      "parameters": {
        "allowed_merge_methods": ["merge"]
      }
    },
    {
      "type": "merge_queue",
      "parameters": {
        "merge_method": "MERGE"
      }
    }
  ]
}
EOF

Ruleset merge method alignment:

Repository SettingRuleset allowed_merge_methodsRuleset merge_queue.merge_method
allow_merge_commit: true only["merge"]"MERGE"
allow_rebase_merge: true only["rebase"]"REBASE"
allow_squash_merge: true only["squash"]"SQUASH"

PR Comment Resolution Workflow

To enforce PR comment resolution:

  1. Enable "Require conversation resolution" in branch protection
  2. During review:
    • Reviewers leave line-specific comments
    • Author responds to each comment
    • Author clicks "Resolve conversation" after addressing
  3. PR cannot merge until all conversations are resolved
  4. Options for each thread:
    • "Resolve conversation" → Mark as addressed
    • Reply with explanation → Then resolve
    • "Won't fix" with reason → Then resolve

Programmatic Review Thread Resolution (CRITICAL)

IMPORTANT: "Addressing" review comments means BOTH:

  1. Fixing the code
  2. LITERALLY resolving the thread via GitHub GraphQL API

The gh CLI does not support resolving review threads directly. Use GraphQL API.

Step 1: Get unresolved review threads

gh api graphql -f query='{
  repository(owner: "OWNER", name: "REPO") {
    pullRequest(number: NUMBER) {
      reviewThreads(first: 50) {
        nodes {
          id
          isResolved
          path
          line
          comments(first: 1) {
            nodes { body }
          }
        }
      }
    }
  }
}'

Step 2: Resolve each thread by ID

gh api graphql -f query='mutation {
  resolveReviewThread(input: {threadId: "PRRT_xxxxxxxxxxxx"}) {
    thread { isResolved }
  }
}'

Step 3: Verify all threads resolved

gh api graphql -f query='{
  repository(owner: "OWNER", name: "REPO") {
    pullRequest(number: NUMBER) {
      reviewThreads(first: 50) {
        nodes { id isResolved }
      }
    }
  }
}' | jq '.data.repository.pullRequest.reviewThreads.nodes | map(select(.isResolved == false))'

PR Completion Checklist:

  • Code changes pushed and CI passing
  • All review threads LITERALLY resolved via GraphQL API
  • PR title and description updated to reflect final changes
  • Added to merge queue or auto-merge enabled

CODEOWNERS Setup

To configure automatic reviewer assignment:

  1. Create .github/CODEOWNERS
  2. Define ownership patterns (last matching pattern wins):
# Default owners for everything
* @org/maintainers

# Directory ownership
/src/auth/ @org/security-team
/docs/ @org/docs-team

# File pattern ownership
*.sql @org/dba-team
/.github/ @org/maintainers
  1. Enable "Require review from CODEOWNERS" in branch protection

Dependency Auto-Merge Setup

To configure automatic merging of dependency updates:

  1. Configure Dependabot or Renovate (see references/dependency-management.md)
  2. Create auto-merge workflow using appropriate template (see decision matrix below)
  3. Workflow auto-approves and merges minor/patch updates
  4. Major updates require manual review

Auto-Merge Decision Matrix:

Repository ConfigurationTemplateMerge Method
Merge queue enabledauto-merge-queue.yml.templateGraphQL enqueuePullRequest
Branch protection (no queue)auto-merge.yml.templategh pr merge --auto
No branch protectionauto-merge-direct.yml.templategh pr merge --rebase (direct)

Merge Queue Auto-Merge Setup

For repositories with merge queues enabled, the --auto flag and direct merge commands don't work. Use the GraphQL enqueuePullRequest mutation instead.

Key points:

  • The mergeMethod parameter is NOT valid for enqueuePullRequest - merge method is set by queue configuration
  • Use github.event.pull_request.node_id to get the PR's GraphQL node ID
  • The mutation adds the PR to the queue; actual merge happens when queue processes it
# .github/workflows/auto-merge-deps.yml
name: Auto-merge dependency PRs
on:
  pull_request_target:
    types: [opened, synchronize, reopened]

permissions:
  contents: write
  pull-requests: write

jobs:
  auto-merge:
    runs-on: ubuntu-latest
    if: github.actor == 'dependabot[bot]' || github.actor == 'renovate[bot]'
    steps:
      - name: Approve PR
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh pr review --approve "$PR_URL"

      - name: Add to merge queue
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NODE_ID: ${{ github.event.pull_request.node_id }}
        run: |
          gh api graphql -f query='
            mutation($pullRequestId: ID!) {
              enqueuePullRequest(input: {pullRequestId: $pullRequestId}) {
                mergeQueueEntry { id }
              }
            }' -f pullRequestId="$PR_NODE_ID"

Direct Auto-Merge Setup (No Branch Protection)

For repositories without branch protection rules, the --auto flag fails with "Protected branch rules not configured". Use direct merge instead:

# .github/workflows/auto-merge-deps.yml
- name: Merge PR
  env:
    PR_URL: ${{ github.event.pull_request.html_url }}
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  run: gh pr merge --rebase "$PR_URL"

Troubleshooting: Auto-Merge Failures

When auto-merge is enabled but PRs aren't merging automatically:

Step 1: Check repo merge settings vs workflow merge method

# View current merge method settings
gh api repos/{owner}/{repo} --jq '{
  allow_squash_merge,
  allow_merge_commit,
  allow_rebase_merge,
  delete_branch_on_merge
}'

Step 2: Identify merge method mismatch

Workflow UsesRepo Setting RequiredError Message
gh pr merge --squashallow_squash_merge: true"Merge method squash merging is not allowed"
gh pr merge --mergeallow_merge_commit: true"Merge method merge commit is not allowed"
gh pr merge --rebaseallow_rebase_merge: true"Merge method rebase is not allowed"

Step 3: Fix merge method alignment

Either update workflow to match repo settings (gh pr merge --rebase) or update repo:

gh api repos/{owner}/{repo} --method PATCH -f allow_rebase_merge=true

Step 4: Validate required status checks

Status check names must exactly match what workflows produce:

# Compare expected vs actual check names
gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks --jq '.contexts[]'
gh pr checks <number> --json name --jq '.[].name'

Common status check name mismatches:

ExpectedActualIssue
Analyze (javascript-typescript)Analyze (javascript)Language detection
buildBuild / buildWorkflow name prefix
testtest (ubuntu-latest, 18)Matrix parameters

Step 5: Fix and re-trigger

# Update branch protection check names
gh api repos/{owner}/{repo}/branches/main/protection/required_status_checks \
  --method PATCH -f strict=true --input - <<< '{"contexts":["actual-check-name"]}'

# Re-trigger stuck PRs
gh pr update-branch <number> --rebase

Auto-merge compatibility checklist:

CheckCommandExpected
Merge method alignmentgh api repos/{owner}/{repo} --jq '.allow_rebase_merge'Matches workflow flag
Status checks passgh pr checks <number>All green
Status check names matchCompare gh pr checks vs branch protectionExact match
Reviews completegh pr view <number> --json reviewDecisionAPPROVED
No merge conflictsgh pr view <number> --json mergeableMERGEABLE
Auto-merge enabledgh pr view <number> --json autoMergeRequestNot null

GitHub Discussions Setup

To enable Discussions:

  1. Go to Settings → Features → Discussions
  2. Create categories:
    • 📣 Announcements (maintainers only)
    • 💬 General
    • 💡 Ideas
    • 🙏 Q&A (Question/Answer format)
  3. Add Discussions link to issue template chooser

Use Discussions for: Questions, ideas, announcements Use Issues for: Bug reports, confirmed features, actionable tasks

GitHub Releases Configuration

To configure automatic release notes:

  1. Create .github/release.yml:
changelog:
  exclude:
    authors: [dependabot, renovate]
  categories:
    - title: 🚀 Features
      labels: [enhancement]
    - title: 🐛 Bug Fixes
      labels: [bug]
    - title: 📚 Documentation
      labels: [documentation]
  1. Create releases via CLI:
gh release create v1.0.0 --generate-notes

Sub-Issues Configuration

GitHub's sub-issues feature enables parent-child relationships between issues (up to 8 levels, 100 sub-issues per parent). For complete GraphQL API reference, see references/sub-issues.md.

Important: The gh CLI does not support sub-issues directly. Use GraphQL API.

Quick reference:

# Get issue node ID
gh api graphql -f query='{repository(owner:"OWNER",name:"REPO"){issue(number:123){id}}}'

# Add sub-issue (requires node IDs)
gh api graphql -f query='mutation{addSubIssue(input:{issueId:"PARENT_ID",subIssueId:"CHILD_ID"}){issue{number}subIssue{number}}}'

# List sub-issues
gh api graphql -f query='{repository(owner:"OWNER",name:"REPO"){issue(number:123){subIssues(first:50){nodes{number title state}}}}}'

Troubleshooting: PR Merge Blocked

When a PR cannot be merged, diagnose the cause:

Step 1: Check PR status

# View PR details including merge state
gh pr view <number> --json mergeable,mergeStateStatus,reviewDecision,statusCheckRollup

# Check for blocking issues
gh pr checks <number>

Step 2: Identify the blocker

SymptomCauseResolution
BLOCKED mergeStateStatusUnresolved conversationsResolve all review threads
REVIEW_REQUIRED reviewDecisionMissing approvalsRequest reviews from required reviewers
CHANGES_REQUESTED reviewDecisionChanges requestedAddress feedback, request re-review
Failed checks in statusCheckRollupCI/CD failuresFix failing tests/lints
CODEOWNERS review requiredMissing code owner approvalGet approval from designated owners

Step 3: Resolution actions

# For unresolved conversations: view and resolve threads
gh pr view <number> --comments

# For missing reviews: request specific reviewers
gh pr edit <number> --add-reviewer username

# For CODEOWNERS blocking: check which files need review
gh pr view <number> --json files

Common gh pr merge errors:

Error MessageMeaningFix
Pull request is not mergeableBranch protection blockingRun diagnosis steps above
Required status check "X" is expectedCI not run or pendingWait for CI or trigger manually
At least 1 approving review is requiredNo approvals yetRequest and obtain review
Changes were made after the most recent approvalStale approvalRequest re-review
Protected branch rules not configured--auto requires branch protectionUse direct merge or enable branch protection
InputObject 'EnqueuePullRequestInput' doesn't accept argument 'mergeMethod'Invalid GraphQL parameterRemove mergeMethod from mutation - it's set by queue config

Quick CLI Reference

# Repository
gh repo view
gh repo edit --enable-discussions

# Issues
gh issue list
gh issue create
gh issue edit 123 --add-label "priority: high"

# Pull requests
gh pr list
gh pr create
gh pr review --approve
gh pr merge --squash

# Releases
gh release create v1.0.0 --generate-notes

# Labels
gh label create "name" --color "hex" --description "desc"

# Projects
gh project create --title "Project Name"

Resources

ResourcePurpose
references/repository-structure.mdStandard files and directory layout
references/dependency-management.mdDependabot/Renovate and auto-merge patterns
references/sub-issues.mdGitHub sub-issues GraphQL API
references/branch-migration.mdMaster to main migration guide
assets/auto-merge.yml.templateAuto-merge with branch protection (--auto flag)
assets/auto-merge-queue.yml.templateAuto-merge with merge queue (GraphQL mutation)
assets/auto-merge-direct.yml.templateAuto-merge without branch protection
scripts/verify-github-project.shVerification script for project setup

This skill focuses on GitHub platform configuration. For complete project setup:

SkillPurpose
go-developmentGo code patterns, Makefile interface, testing, linting
enterprise-readinessOpenSSF Scorecard, SLSA provenance, signed releases, CI workflow templates
git-workflowGit branching strategies, conventional commits
security-auditDeep security audits (OWASP, CVE analysis)

Skill Coordination

github-project (this skill)
├── Repository configuration
├── Branch protection / rulesets
├── Dependabot/Renovate auto-merge
└── Coordinates with:
    ├── go-development → CI workflow content (test, lint, build)
    └── enterprise-readiness → Security workflows (Scorecard, CodeQL, SLSA)

License

This project uses split licensing:

  • Code (scripts, workflows, configs): MIT
  • Content (skill definitions, documentation, references): CC-BY-SA-4.0

See the individual license files for full terms.

Made with ❤️ for Open Source by Netresearch

Verification

To check GitHub project configuration:

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

Checks: documentation files, CODEOWNERS, dependency management, issue/PR templates, auto-merge workflow, release configuration.