GitHub Project Skill

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 full flow (baseline, required checks, merge queue).

🔌 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

Marketplace (Recommended)

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

# Claude Code
/plugin marketplace add netresearch/claude-code-marketplace
/plugin install github-project@netresearch-claude-code-marketplace

Without a marketplace

Since Claude Code 2.1.157 a plugin directory under your personal skills directory loads on its own:

mkdir -p ~/.claude/skills
git clone https://github.com/netresearch/github-project-skill.git \
  ~/.claude/skills/github-project

It loads as github-project@skills-dir on the next session. Update with git -C ~/.claude/skills/github-project pull and start a new session; remove it by deleting the directory. This route has no claude plugin update.

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:

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:

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:

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

A PUT replaces every field it sends as a whole: a rules array holding only the two changed rules deletes all other rules of the ruleset, and GitHub rejects a pull_request or merge_queue rule that does not carry all of its required parameters. Read the ruleset, change the two fields, and send the full rules array back. The REST reference marks no top-level field of the PUT as required; that a field left out (bypass_actors, conditions) is kept is not tested here, so read the ruleset back.

For merge commits only:

gh api repos/{owner}/{repo}/rulesets/{ruleset_id} --jq '{rules: [.rules[]
    | if .type == "pull_request" then .parameters.allowed_merge_methods = ["merge"]
      elif .type == "merge_queue" then .parameters.merge_method = "MERGE"
      else . end
    | if .parameters == null then del(.parameters) else . end]}' \
  | gh api repos/{owner}/{repo}/rulesets/{ruleset_id} -X PUT --input -
# Read it back: the same rules and bypass actors as before, with the two fields changed
gh api repos/{owner}/{repo}/rulesets/{ruleset_id} --jq '{bypass_actors, conditions, rules}'

Ruleset merge method alignment:

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

1. PR cannot merge until all conversations are resolved
2. 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:

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

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:

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:

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)

1. 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

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:

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

Related Skills

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

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)

Tests

The behavioural tests live in tests/ and run offline; they need bash, git, jq, python3 and the usual coreutils, grep and sed:

bash tests/verify-github-project.sh    # skills/github-project/scripts/verify-github-project.sh
bash tests/init-branch-protection.sh   # skills/github-project/scripts/init-branch-protection.sh
bash tests/check-plugin-version.sh     # Build/Scripts/check-plugin-version.sh and Build/hooks/pre-push
bash tests/checkpoint-gh-37.sh         # checkpoint GH-37 in skills/github-project/checkpoints.yaml

• tests/verify-github-project.sh runs the verifier against fixture directories; only the dotted-name fixture has a github.com origin, and the three remote fixtures run with a stub gh on PATH, so no fixture reaches the network. The stub checks that a non-GitHub remote and a host that merely contains github.com trigger no call and that a github.com remote whose name contains a dot is queried with its slug. It checks the exit codes, that all 12 sections run, and individual pass and failure lines, including the default-branch check in a git repository.
• tests/init-branch-protection.sh puts a stub gh first on PATH that answers from prepared responses and records every request and request body. It checks each exit code documented in the script header, the body sent with PUT (with and without --solo), that nothing is written over protection the script could not read, that drift is reported and not corrected, both --from-current-checks paths (with strict false under a merge queue), and --merge-queue: the ruleset body and its read-back, the strict PATCH, the allow_auto_merge PATCH and its read-back, the no-op on an existing standard queue, and each refusal, including a required Analyze (…) context under CodeQL default setup (allowed without default setup and as a workflow-prefixed codeql / Analyze (…)) and "app_id": -1 for unpinned contexts in the printed PATCH.
• tests/check-plugin-version.sh builds throwaway git repositories and checks that a semver tag at HEAD must match the version in .claude-plugin/plugin.json, and that the pre-push hook passes the result on.
• tests/checkpoint-gh-37.sh reads GH-37's script out of checkpoints.yaml and runs it in fixture directories: the org preset as github> or local> (with :preset or #ref, in JSON, JSONC or JSON5) and a repository without a Renovate config pass; config:recommended alone, the preset only in a comment, a description or ignorePresets, a look-alike repository name, a missing extends, and a preset in a later config file than the one Renovate reads fail.

Each check prints ok or FAIL; a FAIL line names the expectation that was not met and is followed by the script's output. A test file exits 1 when any check failed. In CI, the Skill Tests workflow (.github/workflows/tests.yml) runs every tests/**/*.sh on each pull request and on pushes to main, and fails when the repository ships scripts under skills/*/scripts/ but no test ran.

The skill's Markdown and templates are not executed here; Skill Validation and Eval Validation check their structure and the eval definitions in skills/github-project/evals/evals.json. A pull request that adds or changes behaviour in a script adds or updates a check in tests/ that fails without the change.

Governance and policies

This repository follows the Netresearch organisation policies:

• Governance: ownership, roles, how decisions are made and disputes resolved, and continuity.
• Roadmap: planned and explicitly excluded work for the coming year.
• Handling of dependency and code analysis findings: thresholds, deadlines and the exception process for dependency (SCA) and static analysis (SAST) findings.
• Secret management: how CI and release credentials are stored, accessed and rotated.
• Access roster: who holds administrative access to this repository and the organisation.

The security assurance case for this skill (threat model, trust boundaries, countermeasures and limits) is in docs/SECURITY-ASSURANCE.md.

Checks that run on pull requests in this repository:

• Every pull request: Skill Validation (lint.yml: skill structure, markdownlint, yamllint, actionlint, JSON syntax, ShellCheck, ruff, checkpoint schema), Eval Validation (eval-validate.yml) and Skill Tests (tests.yml).
• Pull requests to main: security.yml with Betterleaks (secret scanning), zizmor (workflow static analysis), dependency review, Composer Audit and Opengrep SAST (both behind a preflight event-gate job), and CodeQL for actions; Harness Verification (harness-verify.yml) and Template Drift (check-template-drift.yml). The organisation's security policy sets when dependency review and Opengrep fail: see dependencies and static analysis (SAST).
• Also on every pull request: Labeler (labeler.yml), the DCO sign-off check, SonarCloud Code Analysis and the CodeRabbit review status (GitHub Apps) and, for dependency-update pull requests, auto-merge (auto-merge-deps.yml).

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](https://www.netresearch.de/)

Verification

To check GitHub project configuration:

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

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