github-project

Original source / Raw SKILL.md

---
name: github-project
description: "GitHub repository setup and configuration. This skill should be used when creating new GitHub repositories, configuring branch protection or rulesets, setting up CODEOWNERS, or troubleshooting PR merge issues. By Netresearch."
---

# GitHub Project Skill

## Triggers

- Creating a new GitHub repository
- Configuring branch protection rules or rulesets
- Setting up CODEOWNERS
- Troubleshooting "merge is blocked" or "not allowed merge method" errors
- Configuring auto-merge for Dependabot/Renovate

## Usage

For workflows, CLI commands, templates, and troubleshooting guides, see `README.md`.

Key references:
- `references/repository-structure.md` - Standard repo layout
- `references/sub-issues.md` - Sub-issues GraphQL API
- `references/dependency-management.md` - Dependabot/Renovate configuration
- `templates/` - Auto-merge workflow templates

## Go Project CI Checklist

For Go projects, ensure these GitHub configurations:

| Setting | Purpose | How |
|---------|---------|-----|
| Branch protection | Require tests pass before merge | Branch settings or Rulesets |
| Dependabot/Renovate | Automated dependency updates | `.github/dependabot.yml` or `renovate.json` |
| Auto-merge workflow | Merge minor/patch updates automatically | `templates/auto-merge*.yml` |
| Required checks | CI workflow names in branch protection | Match exact workflow job names |

For CI/CD workflow content (test, lint, build), see `go-development` skill.
For security workflows (Scorecard, CodeQL, SLSA), see `enterprise-readiness` skill.

## Related Skills

| Skill | Purpose |
|-------|---------|
| `go-development` | Go code patterns, Makefile interface, testing, linting |
| `enterprise-readiness` | OpenSSF Scorecard, SLSA provenance, signed releases |
| `git-workflow` | Git branching strategies, conventional commits |
| `security-audit` | Deep security audits (OWASP, CVE analysis) |


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/repository-structure.md

```markdown
# Repository Structure Reference

Standard files and directories for GitHub open source projects.

## Root Directory Files

### README.md
Primary project documentation visible on repository homepage.

**Essential Sections:**
```markdown
# Project Name

Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Installation
```bash
# Installation commands
```

## Quick Start
```bash
# Usage example
```

## Documentation
Link to full docs

## Contributing
Link to CONTRIBUTING.md

## License
License type with link
```

### LICENSE
Standard open source license file.

**Common Choices:**
| License | Use Case |
|---------|----------|
| MIT | Maximum permissiveness |
| Apache-2.0 | Patent protection |
| GPL-3.0 | Copyleft requirement |
| BSD-3-Clause | Simple permissive |

### CHANGELOG.md
Version history following [Keep a Changelog](https://keepachangelog.com/) format.

**Structure:**
```markdown
# Changelog

## [Unreleased]

## [1.2.0] - 2024-01-15
### Added
- New feature X

### Changed
- Updated behavior Y

### Fixed
- Bug in Z

### Removed
- Deprecated feature W
```

### CONTRIBUTING.md
Contributor guidelines and development setup.

**Essential Sections:**
- Development environment setup
- Code style requirements
- Testing expectations
- Pull request process
- Commit message format

### CODE_OF_CONDUCT.md
Community behavior standards.

**Recommended:** [Contributor Covenant](https://www.contributor-covenant.org/) v2.1

### SECURITY.md
Security policy and vulnerability reporting.

**Essential Sections:**
- Supported versions
- Reporting process (GitHub Security Advisories preferred)
- Response timeline
- Security measures in place

### GOVERNANCE.md
Project decision-making structure.

**Models:**
- BDFL (Benevolent Dictator For Life)
- Meritocracy
- Liberal contribution
- Technical steering committee

## .github Directory

### CODEOWNERS
Automatic review assignment.

```
# Default owners
* @org/maintainers

# Directory-specific
/src/ @org/core-team
/.github/ @org/maintainers
/SECURITY.md @org/security-team
```

### dependabot.yml
Automated dependency updates.

### renovate.json
Alternative to Dependabot with more configuration options.

### ISSUE_TEMPLATE/
- `bug_report.md` - Bug report template
- `feature_request.md` - Feature request template
- `config.yml` - Issue template chooser configuration

### PULL_REQUEST_TEMPLATE.md
Standard PR description format.

### workflows/
GitHub Actions workflow files.

**Common Workflows:**
| File | Purpose |
|------|---------|
| ci.yml | Continuous integration |
| release.yml | Release automation |
| scorecard.yml | OpenSSF Scorecard |
| auto-merge.yml | Dependency auto-merge |

## Language-Specific Files

### Go Projects
```
project/
├── go.mod
├── go.sum
├── .golangci.yml
├── .goreleaser.yml (optional)
└── .slsa-goreleaser/ (for SLSA releases)
```

### PHP/TYPO3 Projects
```
project/
├── composer.json
├── composer.lock
├── .php-cs-fixer.php
├── phpstan.neon
├── rector.php
└── Build/
    └── phpunit/
```

### Node.js Projects
```
project/
├── package.json
├── package-lock.json
├── .eslintrc.js
├── .prettierrc
└── tsconfig.json (TypeScript)
```

## Directory Structure Patterns

### By Feature (Recommended)
```
project/
├── cmd/           # Go: Entry points
├── internal/      # Go: Private packages
├── pkg/           # Go: Public packages
├── Classes/       # PHP: Source code
├── src/           # Generic: Source code
├── tests/         # Test files
├── docs/          # Documentation
└── scripts/       # Utility scripts
```

### By Layer
```
project/
├── controllers/
├── services/
├── repositories/
├── models/
└── utils/
```

## Best Practices

1. **Keep root clean**: Only essential config files at root
2. **Group related files**: Use directories for organization
3. **Follow conventions**: Use standard names (src/, tests/, docs/)
4. **Document structure**: Include structure explanation in README
5. **Ignore properly**: Maintain comprehensive .gitignore

```

### references/sub-issues.md

```markdown
# Sub-Issues Reference

GitHub's sub-issues feature enables parent-child relationships between issues, supporting up to 8 levels of hierarchy and 100 sub-issues per parent. This replaced the deprecated tasklists feature (sunset April 2025).

**Important:** The `gh` CLI does not support sub-issues directly. You must use the GraphQL API.

## Creating Sub-Issues

**Step 1: Create the issues normally**
```bash
# Create parent issue
gh issue create --title "Parent feature request" --body "Main tracking issue"
# Returns: https://github.com/owner/repo/issues/100

# Create child issues
gh issue create --title "Sub-task 1" --body "First sub-task"
# Returns: https://github.com/owner/repo/issues/101

gh issue create --title "Sub-task 2" --body "Second sub-task"
# Returns: https://github.com/owner/repo/issues/102
```

**Step 2: Get issue node IDs (required for GraphQL)**
```bash
gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    parent: issue(number: 100) { id }
    child1: issue(number: 101) { id }
    child2: issue(number: 102) { id }
  }
}'
```

Output:
```json
{
  "data": {
    "repository": {
      "parent": { "id": "I_kwDOXXXXXX" },
      "child1": { "id": "I_kwDOYYYYYY" },
      "child2": { "id": "I_kwDOZZZZZZ" }
    }
  }
}
```

**Step 3: Link sub-issues to parent**
```bash
# Add first sub-issue
gh api graphql -f query='
mutation {
  addSubIssue(input: {
    issueId: "I_kwDOXXXXXX",
    subIssueId: "I_kwDOYYYYYY"
  }) {
    issue { number title }
    subIssue { number title }
  }
}'

# Add second sub-issue
gh api graphql -f query='
mutation {
  addSubIssue(input: {
    issueId: "I_kwDOXXXXXX",
    subIssueId: "I_kwDOZZZZZZ"
  }) {
    issue { number title }
    subIssue { number title }
  }
}'
```

## Querying Sub-Issues

**List all sub-issues of a parent:**
```bash
gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    issue(number: 100) {
      number
      title
      subIssues(first: 50) {
        nodes {
          number
          title
          state
        }
        totalCount
      }
    }
  }
}'
```

**Get parent of a sub-issue:**
```bash
gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    issue(number: 101) {
      number
      title
      parent {
        number
        title
      }
    }
  }
}'
```

## Removing Sub-Issues

```bash
gh api graphql -f query='
mutation {
  removeSubIssue(input: {
    issueId: "I_kwDOXXXXXX",
    subIssueId: "I_kwDOYYYYYY"
  }) {
    issue { number }
    subIssue { number }
  }
}'
```

## Best Practices

| Practice | Rationale |
|----------|-----------|
| Use parent as tracking/meta issue | Provides overview and progress tracking |
| Add "tracking" label to parent | Identifies meta-issues in issue lists |
| Keep hierarchy ≤3 levels | Deeper hierarchies become hard to manage |
| Reference upstream PRs in body | Link to external sources for context |
| One sub-issue per distinct feature | Enables independent progress and assignment |

## Sub-Issues Behavior

- **Inheritance**: Sub-issues inherit Project and Milestone from parent by default
- **Cross-org support**: Sub-issues can belong to different organizations than parent
- **Progress tracking**: Parent issue shows completion percentage in GitHub UI
- **Limits**: Maximum 100 sub-issues per parent, 8 levels of nesting

## Migration from Tasklists

Tasklists were sunset April 30, 2025. To convert old tasklist items:

1. Identify issues with tasklist markdown (`- [ ] #123`)
2. Create sub-issue relationships using GraphQL API above
3. Remove tasklist markdown from issue body (or leave as reference)

## Quick Reference

```bash
# 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}}}}}'

# Remove sub-issue
gh api graphql -f query='mutation{removeSubIssue(input:{issueId:"PARENT_ID",subIssueId:"CHILD_ID"}){issue{number}}}'
```

```

### references/dependency-management.md

```markdown
# Dependency Management Reference

Dependabot and Renovate configuration patterns.

## Dependabot

### Basic Configuration
```yaml
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
      day: "monday"
      time: "06:00"
      timezone: "Europe/Berlin"
```

### Package Ecosystems

| Ecosystem | Languages/Tools |
|-----------|-----------------|
| gomod | Go modules |
| npm | JavaScript/Node.js |
| composer | PHP |
| pip | Python |
| cargo | Rust |
| maven | Java |
| gradle | Java/Kotlin |
| nuget | .NET |
| bundler | Ruby |
| docker | Dockerfiles |
| github-actions | GitHub Actions |
| terraform | Terraform |

### Grouping Dependencies
```yaml
updates:
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      all-dependencies:
        patterns:
          - "*"

      # Or group by type
      production:
        dependency-type: "production"
      development:
        dependency-type: "development"
```

### Commit Message Prefixes
```yaml
updates:
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "deps"
      prefix-development: "deps(dev)"
      include: "scope"
    labels:
      - "dependencies"
```

### Multiple Ecosystems
```yaml
version: 2
updates:
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      dependencies:
        patterns:
          - "*"
    commit-message:
      prefix: "deps"
    labels:
      - "dependencies"

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      github-actions:
        patterns:
          - "*"
    commit-message:
      prefix: "ci"
    labels:
      - "dependencies"
      - "github-actions"

  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "docker"
    labels:
      - "dependencies"
      - "docker"
```

### Ignoring Dependencies
```yaml
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "lodash"
        versions: [">=5.0.0"]
      - dependency-name: "react"
        update-types: ["version-update:semver-major"]
```

### Reviewers and Assignees
```yaml
updates:
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
    reviewers:
      - "username"
      - "org/team-name"
    assignees:
      - "username"
```

## Renovate

### Basic Configuration
```json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended"
  ]
}
```

### Extended Configuration
```json
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": [
    "config:recommended",
    ":semanticCommits",
    ":semanticCommitTypeAll(chore)",
    "group:allNonMajor"
  ],
  "labels": ["dependencies"],
  "prHourlyLimit": 2,
  "prConcurrentLimit": 5,
  "timezone": "Europe/Berlin",
  "schedule": ["before 7am on monday"]
}
```

### Auto-merge Configuration
```json
{
  "extends": ["config:recommended"],
  "packageRules": [
    {
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    },
    {
      "matchManagers": ["github-actions"],
      "groupName": "GitHub Actions",
      "automerge": true
    },
    {
      "matchDepTypes": ["devDependencies"],
      "automerge": true
    }
  ]
}
```

### Grouping Rules
```json
{
  "extends": ["config:recommended"],
  "packageRules": [
    {
      "matchPackagePatterns": ["^@types/"],
      "groupName": "TypeScript types"
    },
    {
      "matchPackagePatterns": ["eslint"],
      "groupName": "ESLint"
    },
    {
      "matchPackagePatterns": ["^react"],
      "groupName": "React"
    }
  ]
}
```

### Security Updates
```json
{
  "extends": [
    "config:recommended",
    ":enableVulnerabilityAlerts"
  ],
  "vulnerabilityAlerts": {
    "labels": ["security"],
    "automerge": true
  }
}
```

### PHP/Composer Configuration
```json
{
  "extends": ["config:recommended"],
  "composer": {
    "enabled": true
  },
  "packageRules": [
    {
      "matchPackagePatterns": ["^typo3/"],
      "groupName": "TYPO3"
    },
    {
      "matchPackagePatterns": ["^phpstan/", "^phpunit/"],
      "groupName": "PHP dev tools"
    }
  ]
}
```

### Go Configuration
```json
{
  "extends": ["config:recommended"],
  "gomod": {
    "enabled": true
  },
  "packageRules": [
    {
      "matchManagers": ["gomod"],
      "matchUpdateTypes": ["minor", "patch"],
      "automerge": true
    }
  ]
}
```

## Auto-merge Workflow

### Auto-merge Decision Matrix

| Repository Configuration | Workflow Pattern | Key Difference |
|--------------------------|------------------|----------------|
| Merge queue enabled | GraphQL `enqueuePullRequest` | Adds PR to queue, queue handles merge |
| Branch protection (no queue) | `gh pr merge --auto` | Enables auto-merge, GitHub merges when checks pass |
| No branch protection | `gh pr merge --rebase` | Direct merge, no waiting |

### GitHub Actions Auto-merge (Branch Protection)
```yaml
# .github/workflows/auto-merge.yml
# Use when: Branch protection enabled, no merge queue
name: Auto-merge dependency updates

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: Harden Runner
        uses: step-security/harden-runner@v2
        with:
          egress-policy: audit

      - name: Auto-approve PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Enable auto-merge
        run: gh pr merge --auto --squash "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### GitHub Actions Auto-merge (Merge Queue)
```yaml
# .github/workflows/auto-merge-deps.yml
# Use when: Repository has merge queue enabled
# IMPORTANT: mergeMethod is NOT a valid argument for enqueuePullRequest
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: Auto-approve PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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

### GitHub Actions Auto-merge (No Branch Protection)
```yaml
# .github/workflows/auto-merge-deps.yml
# Use when: No branch protection rules configured
# Note: --auto flag requires branch protection, use direct merge instead
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: Auto-approve PR
        run: gh pr review --approve "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Merge PR
        run: gh pr merge --rebase "$PR_URL"
        env:
          PR_URL: ${{ github.event.pull_request.html_url }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Dependabot Auto-merge Metadata
```yaml
# Check metadata for safer auto-merge
- name: Dependabot metadata
  id: metadata
  uses: dependabot/fetch-metadata@v2
  with:
    github-token: "${{ secrets.GITHUB_TOKEN }}"

- name: Auto-merge minor/patch
  if: steps.metadata.outputs.update-type != 'version-update:semver-major'
  run: gh pr merge --auto --squash "$PR_URL"
  env:
    PR_URL: ${{ github.event.pull_request.html_url }}
    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Comparison: Dependabot vs Renovate

| Feature | Dependabot | Renovate |
|---------|------------|----------|
| Hosting | GitHub native | Self-hosted or app |
| Configuration | YAML | JSON/JSON5 |
| Grouping | Basic | Advanced |
| Auto-merge | Via workflow | Native support |
| Custom managers | Limited | Regex support |
| Dashboard | Basic | Dependency Dashboard |
| Presets | Limited | Extensive |
| Update types | All | Granular control |

### When to Use Dependabot
- GitHub-only projects
- Simple dependency management
- Native GitHub integration preferred
- Limited configuration needs

### When to Use Renovate
- Complex grouping requirements
- Multiple repositories
- Advanced auto-merge rules
- Custom package managers
- Dependency Dashboard needed
- Cross-platform support

## Best Practices

1. **Group related updates**: Reduce PR noise
2. **Use semantic commit prefixes**: Better changelogs
3. **Enable auto-merge for safe updates**: minor/patch
4. **Require CI checks**: Before auto-merge
5. **Review major updates manually**: Breaking changes
6. **Schedule updates**: Off-peak hours
7. **Label PRs**: Easy filtering
8. **Limit concurrent PRs**: Avoid CI overload

```