Download the PHP package netresearch/agent-github-project without Composer

name: github-project description: "GitHub repository setup and platform-specific features. This skill should be used when creating new GitHub repositories, configuring branch protection rules, setting up GitHub Issues/Discussions/Projects, creating sub-issues and issue hierarchies, managing PR review workflows, configuring Dependabot/Renovate auto-merge, setting up merge queues with GraphQL enqueuePullRequest mutations, or checking GitHub project configuration. Focuses on GitHub platform features, not CI/CD pipelines or language-specific tooling. By Netresearch."

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

Marketplace (Recommended)

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

npx (skills.sh)

Install with any Agent Skills-compatible agent:

Download Release

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

Git Clone

Composer (PHP Projects)

Requires netresearch/composer-agent-skill-plugin.

npm (Node Projects)

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:

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:

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:

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:

Branch Protection Configuration

To configure branch protection via GitHub CLI:

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:

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:

Fix: Update ruleset to match repository settings

For merge commits only:

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

Step 2: Resolve each thread by ID

Step 3: Verify all threads resolved

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):

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

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:

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

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:

Step 4: Validate required status checks

Status check names must exactly match what workflows produce:

Common status check name mismatches:

Step 5: Fix and re-trigger

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)
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:

2. Create releases via CLI:

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:

Troubleshooting: PR Merge Blocked

When a PR cannot be merged, diagnose the cause:

Step 1: Check PR status

Step 2: Identify the blocker

Step 3: Resolution actions

Common gh pr merge errors:

Quick CLI Reference

Resources

Related Skills

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

Skill Coordination

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:

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