GitHub Repository Setup Guide¶

This guide documents the recommended GitHub repository settings for maintainers and collaborators.

Branch Protection Rules¶

Main Branch Protection (main)¶

Configure branch protection at: Settings → Branches → Add rule

Required Settings¶

Required Status Checks¶

Add these checks (must pass before merge):

• ✅ lint - ShellCheck on mise tasks
• ✅ docs-validate - Markdown link validation
• ✅ docs-build - MkDocs build success
• ✅ build - Main test suite (fast tests)
• ✅ test-server-deployment - Dotfiles-only mode validation
• ✅ test-windows - Windows provisioning tests

Configuration path: Settings → Branches → Edit rule → Require status checks

CODEOWNERS Configuration¶

File: .github/CODEOWNERS

Automatically requests reviews from specified users/teams for matching paths.

Current Configuration¶

# Default owner for everything
* @jerdaw

# Critical configuration files
/.github/ @jerdaw
/mise.toml @jerdaw
/.chezmoiversion @jerdaw

How It Works¶

1. PR modifies .github/workflows/ci.yml
2. GitHub automatically requests review from @jerdaw
3. Branch protection enforces review before merge

Extending CODEOWNERS¶

Add team-specific ownership:

# Documentation
/docs/ @documentation-team

# Windows support
/mise-tasks/setup/provision/windows/ @windows-maintainers

# Security-sensitive
/dot_config/age/ @security-team

Pull Request Settings¶

Configuration path: Settings → General → Pull Requests

Recommended Settings¶

Pull Request Template¶

File: .github/PULL_REQUEST_TEMPLATE.md

Provides checklist for contributors. Review PRs for: - [ ] Follows file naming conventions - [ ] Documentation updated - [ ] CHANGELOG.md updated (if user-facing) - [ ] Tests pass (mise run test) - [ ] Doctor passes (mise run doctor) - [ ] Platform-specific considerations addressed

Issue Templates¶

Location: .github/ISSUE_TEMPLATE/

Configured templates help users provide necessary information.

Available Templates¶

1. Bug Report - For reporting issues
2. Feature Request - For suggesting enhancements
3. Question - For general questions

Managing Templates¶

Edit templates at: Settings → Features → Issues → Set up templates

GitHub Actions Settings¶

Configuration path: Settings → Actions → General

Workflow Permissions¶

Specific Workflow Permissions¶

Workflows define explicit permissions (least-privilege):

ci.yml:

permissions:
  contents: read
  pull-requests: write  # For step summaries

docs.yml:

permissions:
  contents: write  # For gh-pages push

Renovate Configuration¶

File: .github/renovate.json

Automates dependency updates with smart automerge rules.

Current Strategy¶

• Automerge: Patch updates only (e.g., 1.2.3 → 1.2.4)
• Manual review: Minor updates (e.g., 1.2.x → 1.3.0)
• Manual review: Major updates (e.g., 1.x.x → 2.0.0)
• Grouping: Related updates bundled together

How It Works¶

1. Renovate detects outdated dependencies
2. Creates PR with update
3. CI runs automatically
4. If patch update + CI passes → Auto-merge
5. If minor/major → Waits for manual review

Adjusting Renovate¶

Edit .github/renovate.json:

{
  "extends": ["config:base"],
  "automerge": true,
  "automergeType": "pr",
  "automergeStrategy": "squash",
  "packageRules": [
    {
      "matchUpdateTypes": ["patch"],
      "automerge": true
    }
  ]
}

Secrets Management¶

Configuration path: Settings → Secrets and variables → Actions

Repository Secrets¶

Currently configured: - GITHUB_TOKEN - Automatic, provided by GitHub

Adding Secrets (If Needed)¶

For age encryption: 1. Go to Settings → Secrets → New repository secret 2. Name: AGE_SECRET_KEY 3. Value: Your age private key 4. Reference in workflow:

- name: Decrypt secrets
  env:
    AGE_SECRET_KEY: ${{ secrets.AGE_SECRET_KEY }}
  run: age -d -i <(echo "$AGE_SECRET_KEY") secrets.age

Security best practices: - Never commit secrets to repository - Use age encryption for sensitive dotfiles - Rotate secrets if compromised - See SECURITY.md and SECRETS.md

GitHub Pages Settings¶

Configuration path: Settings → Pages

Current Configuration¶

How Documentation Deploys¶

1. Push to main (docs changes)
2. docs.yml workflow triggers
3. MkDocs builds site
4. gh-deploy pushes to gh-pages branch
5. GitHub Pages serves from gh-pages

URL: https://<username>.github.io/dotfiles/

Collaborator Access Levels¶

Configuration path: Settings → Collaborators and teams

Access Levels¶

Recommendations¶

• Owner: Admin access
• Core maintainers: Maintain access
• Regular contributors: Write access (if needed, or use forks)
• Documentation contributors: Write or Triage

Notifications & Watching¶

For Maintainers¶

Recommended watch settings: 1. Go to repository 2. Click "Watch" → "Custom" 3. Enable: - ✅ Issues - ✅ Pull requests - ✅ Releases - ✅ Discussions (if enabled) - ✅ Security alerts

Email Notifications¶

Configure at: Settings → Notifications

Receive emails for: - PR reviews requested - CI failures on your branches - Dependency security alerts - Renovate updates (if desired)

Security Settings¶

Configuration path: Settings → Code security and analysis

Recommended Enabling¶

Secret Scanning¶

Alerts if secrets (API keys, tokens) are committed: - GitHub automatically detects common patterns - Sends alert to repository admins - Recommends rotating compromised secrets

Note: Also using gitleaks in pre-commit hooks for local scanning.

Repository Settings Checklist¶

Use this checklist when setting up a new fork or mirror:

General¶

• Repository name and description set
• Topics added (dotfiles, chezmoi, mise, zsh)
• README.md appears on homepage
• License specified (if applicable)

Access¶

• Collaborators added with appropriate roles
• Teams configured (if organization)

Branches¶

• Default branch is main
• Branch protection rules configured
• Required status checks enabled
• CODEOWNERS enforced

Pull Requests¶

• PR template configured
• Auto-delete head branches enabled
• Auto-merge enabled

Issues¶

• Issue templates configured
• Labels organized

Actions¶

• Workflows enabled
• Workflow permissions set correctly
• Secrets configured (if needed)

Security¶

• Dependabot alerts enabled
• Secret scanning enabled
• SECURITY.md present and linked

Pages¶

• GitHub Pages enabled
• Deploy from gh-pages branch
• HTTPS enforced

Maintenance Tasks¶

Regular (Weekly/Monthly)¶

• Review Renovate PRs and merge
• Check Dependabot security alerts
• Review open issues and PRs
• Update CHANGELOG.md and ROADMAP.md

Occasional (Quarterly/Yearly)¶

• Review branch protection rules
• Audit collaborator access
• Review CODEOWNERS accuracy
• Update GitHub Actions workflows
• Review and update documentation

Related Documentation¶

• CONTRIBUTING.md - Contribution guidelines
• SECURITY.md - Security policy and reporting
• CODEOWNERS - Code ownership assignments
• PULL_REQUEST_TEMPLATE.md - PR template
• renovate.json - Dependency automation config

Getting Help¶

GitHub Settings Issues¶

If you can't access Settings: - Check your role (requires Admin or Maintain access) - Contact repository owner for permissions

Workflow Failures¶

See CI-TROUBLESHOOTING.md for debugging CI/CD issues.

Security Concerns¶

See SECURITY.md for reporting security vulnerabilities.