GitHub Repository Setup for Public Contributions

GitHub Repository Setup for Public Contributions

Last Updated: 2025-11-30 Repository: claude-mpm-skills Maintainer: @bobmatnyc

Table of Contents

• 1. Overview
• 2. General Settings
• 3. Branch Protection Rules
• 4. Security Settings
• 5. GitHub Actions Settings
• 6. Issue and PR Settings
• 7. Discussions Settings
• 8. Labels Setup
• 9. Collaborators and Teams
• 10. Repository Insights
• 11. Pre-Launch Checklist
• 12. Post-Launch Monitoring
• 13. Automated CI Workflows
• Appendix A: Label Creation Script
• Appendix B: Troubleshooting

1. Overview

Purpose of This Document

This guide provides step-by-step instructions to configure the claude-mpm-skills repository for safe, high-quality public contributions. These settings enable:

• Quality Control: Branch protection and required reviews prevent broken code from merging
• Automated Validation: CI workflows enforce skill self-containment standards
• Community Safety: Security policies and code of conduct protect contributors
• Efficient Triage: Label taxonomy and issue templates streamline issue management
• Contributor Experience: Clear templates and guidelines reduce friction

When to Apply These Settings

Before making the repository public or accepting external contributions. This prevents:

• Direct commits to main branch
• Merging of malformed skills or sensitive data
• Unclear contribution expectations
• Security vulnerabilities being publicly disclosed

How to Access Repository Settings

1. Navigate to https://github.com/OWNER/claude-mpm-skills
2. Click Settings tab (requires admin/owner permissions)
3. Follow section-specific instructions below

Note: Some settings require repository admin or owner permissions.

2. General Settings

Navigate to: Settings → General

Repository Details

Description:

Production-ready Claude Code skills for intelligent project development

Website:

https://github.com/OWNER/claude-mpm-skills#readme

(Update with documentation site URL if available)

Topics/Tags:

Add the following topics for discoverability:

claude-code
claude
anthropic
skills
ai-development
development-tools
project-management
automation
typescript
python
nextjs
ai-workflows
code-generation
developer-productivity
mcp-servers

How to add:

1. Click "⚙️" next to "About" section on repository homepage
2. Add topics in "Topics" field (comma-separated)
3. Click "Save changes"

Features to Enable

Configuration Steps:

1. Go to Settings → General → Features
2. Check/uncheck boxes according to table above
3. Scroll down and click Save

3. Branch Protection Rules for main

Navigate to: Settings → Branches → Add branch protection rule

Required Configuration

Branch name pattern:

main

Pull Request Requirements

✅ Require a pull request before merging

• ✅ Require approvals: 1
  • Rationale: Single maintainer workflow, ensures code review
• ✅ Dismiss stale pull request approvals when new commits are pushed
  • Rationale: Prevents outdated approvals after significant changes
• ✅ Require review from Code Owners
  • Rationale: .github/CODEOWNERS exists and routes to @bobmatnyc
• ❌ Require approval of the most recent reviewable push
  • Rationale: Optional - adds extra review burden for small changes

✅ Require status checks to pass before merging

• ✅ Require branches to be up to date before merging
  • Rationale: Prevents merge conflicts and ensures latest code tested
• Status checks that are required:
  • ✅ validate / validate (from .github/workflows/validate-skills.yml)

How to add required checks:

1. After enabling "Require status checks", a search box appears
2. Type validate and select validate / validate
3. If not visible, ensure the workflow has run at least once on a PR

✅ Require conversation resolution before merging

• Rationale: All review comments must be addressed before merge

⚠️ Require signed commits (Optional - Recommended)

• Rationale: Increases security, verifies commit authorship
• Trade-off: Adds setup burden for new contributors
• Recommendation: Enable if security is paramount, otherwise skip initially

❌ Require linear history

• Rationale: Too strict for open source - requires rebasing knowledge
• Recommendation: Disabled for contributor friendliness

❌ Require deployments to succeed before merging

• Rationale: N/A for skill library (no deployment process)

Enforcement Settings

✅ Do not allow bypassing the above settings

• Rationale: Applies rules to administrators (prevents accidental direct commits)

⚠️ Restrict who can push to matching branches

• Options:
  • Enable and add only @bobmatnyc (strict control)
  • Disable (allow trusted collaborators to push)
• Recommendation: Enable for single-maintainer workflow

❌ Allow force pushes

• Rationale: Never enable - protects commit history

❌ Allow deletions

• Rationale: Never enable - prevents accidental branch deletion

Summary Configuration

Branch name pattern: main

Pull Request Settings:
  ✅ Require pull request reviews (1 approval)
  ✅ Dismiss stale reviews
  ✅ Require Code Owners review

Status Checks:
  ✅ Require status checks to pass
  ✅ Require branches to be up to date
  Required checks:
    - validate / validate

Other Requirements:
  ✅ Require conversation resolution
  ⚠️ Require signed commits (optional)
  ❌ Require linear history

Enforcement:
  ✅ Do not allow bypassing
  ⚠️ Restrict who can push (recommended)
  ❌ Allow force pushes
  ❌ Allow deletions

Save the rule: Click Create or Save changes at bottom of page.

4. Security Settings

Navigate to: Settings → Security & analysis

Recommended Security Features

Configuration Steps

1. Private vulnerability reporting:

   • Click Enable next to "Private vulnerability reporting"
   • Ensure SECURITY.md exists (see Pre-Launch Checklist)

2. Dependency graph:

   • Should be enabled by default for public repos
   • If not, click Enable

3. Dependabot alerts:

   • Click Enable if not already active
   • Alerts appear in Security → Dependabot tab

4. Dependabot security updates:

   • Click Enable
   • Creates PRs automatically when security vulnerabilities found

5. Secret scanning:

   • Available by default for public repositories
   • Verify status shows "Enabled"

6. Secret scanning push protection:

   • Click Enable to block pushes with secrets

Security Policy

Ensure SECURITY.md exists in repository root with vulnerability reporting instructions. See template in Pre-Launch Checklist.

5. GitHub Actions Settings

Navigate to: Settings → Actions → General

Actions Permissions

Actions permissions:

✅ Allow all actions and reusable workflows

Rationale: Open source project benefits from community actions. Monitor for malicious actions in PRs.

Alternative (more restrictive):

⚠️ Allow OWNER, and select non-OWNER, actions and reusable workflows

Use if security is paramount.

Workflow Permissions

Default workflow permissions:

✅ Read repository contents and packages permissions

Rationale: Minimal permissions for CI validation workflows.

Additional permissions:

✅ Allow GitHub Actions to create and approve pull requests

Rationale: Enables automation like Dependabot PRs.

Warning: Do NOT enable write access to repository contents unless absolutely necessary (prevents accidental auto-commits).

Fork Pull Request Workflows

Fork pull request workflows from outside collaborators:

✅ Require approval for first-time contributors

Rationale: Prevents malicious workflows from external contributors.

Fork pull request workflows from contributors:

✅ Require approval for all outside collaborators

Rationale: All external PRs reviewed before running workflows.

Configuration Summary

Actions Permissions:
  ✅ Allow all actions and reusable workflows

Workflow Permissions:
  ✅ Read repository contents and packages
  ✅ Allow GitHub Actions to create and approve pull requests
  ❌ Read and write permissions (contents)

Fork Pull Request Workflows:
  ✅ Require approval for first-time contributors
  ✅ Require approval for all outside collaborators

Save: Scroll down and click Save.

6. Issue and PR Settings

Navigate to: Settings → General → Features

Issue Settings

Issues:

✅ Enable issues

Issue Templates:

• ✅ Already created in .github/ISSUE_TEMPLATE/:
  • bug_report.yml (structured bug reports)
  • feature_request.yml (feature suggestions)
  • new_skill_proposal.yml (skill contribution workflow)
  • config.yml (template chooser configuration)

No additional configuration needed - templates auto-detected by GitHub.

Pull Request Settings

Navigate to: Settings → General → Pull Requests

Merge Button Options:

Recommendation: Enable all three, default to squash merging.

How to set default:

1. Go to Settings → General → Pull Requests
2. Under "Allow merge commits", check the box
3. Under "Allow squash merging", check the box (select as default)
4. Under "Allow rebase merging", check if desired

Additional PR Settings:

Configuration:

1. Check Always suggest updating pull request branches
2. Check Allow auto-merge
3. Check Automatically delete head branches
4. Scroll down and click Save

7. Discussions Settings

Navigate to: Settings → General → Features → Discussions

Enable Discussions

1. Check ✅ Discussions checkbox
2. Click Set up discussions

Create Discussion Categories

GitHub creates default categories. Customize as follows:

How to configure:

1. Go to repository Discussions tab
2. Click ⚙️ (settings icon) or "Edit" next to category
3. Modify name, emoji, description per table
4. For Announcements: Check "Only maintainers can post"
5. Save each category

Discussion Templates (Optional)

Create discussion templates in .github/DISCUSSION_TEMPLATE/:

.github/
└── DISCUSSION_TEMPLATE/
    ├── skill-idea.md
    └── implementation-help.md

Example: skill-idea.md

---
title: "[Skill Idea] "
labels: ["type: new-skill"]
---

## Skill Name
<!-- e.g., "PostgreSQL Query Optimization" -->

## Category
<!-- toolchains/python, universal/, etc. -->

## Use Case
<!-- What problem does this skill solve? -->

## Key Features
<!-- What would this skill include? -->

8. Labels Setup

Label Taxonomy Overview

A comprehensive label system enables efficient issue triage and filtering. Labels are organized into categories:

1. Priority (🟥🟧🟨🟩) - Urgency and importance
2. Status (🚦🔍🚧🏁👀⛔✅) - Workflow state
3. Type (🐛✨🚀📖🔧💬🎨) - Issue classification
4. Skill Category (skill:*) - Domain-specific
5. Effort (effort:*) - Implementation complexity
6. Community (good first issue, help wanted, etc.)
7. Automated (🤖 auto:*) - CI/bot-applied

Label Application Rules

Every issue must have:

1. One priority label (🟥🟧🟨🟩)
2. One type label (🐛✨🚀📖🔧💬🎨)
3. One status label (starts with status: triage)

Optional labels:

• One or more skill:* labels
• One effort:* label (recommended for tasks)
• Community labels as appropriate

Creating Labels

Option 1: Automated Script (Recommended)

See Appendix A: Label Creation Script for complete bash script using GitHub CLI.

Option 2: Manual Creation

Navigate to: Issues → Labels → New label

Create each label with specifications below:

Priority Labels (Mandatory)

Status Labels (Workflow)

Type Labels (Classification)

Skill Category Labels

Effort Labels (Contributor Guidance)

Community Labels

Automated Labels (Applied by CI)

Total Labels: 40

9. Collaborators and Teams

Navigate to: Settings → Access → Collaborators and teams

Recommended Team Structure

Adding Collaborators

1. Click Add people or Add teams
2. Search for GitHub username
3. Select role from dropdown
4. Click Add

Creating Teams (Organization Repos Only)

If repository is under GitHub organization:

1. Go to organization Teams page
2. Click New team
3. Name: claude-mpm-maintainers, claude-mpm-contributors, etc.
4. Add team members
5. In repository settings, add team with appropriate role

Single Maintainer Setup

For @bobmatnyc as sole maintainer:

• No additional collaborators needed initially
• Branch protection ensures all PRs reviewed before merge
• Add trusted contributors over time as community grows

10. Repository Insights

Navigate to: Insights → Community

Community Health Checklist

Verify all items are checked (✅):

Missing items must be created before going public. See Pre-Launch Checklist.

Community Standards Badge

Once all files exist, repository displays "Community standards: Complete" badge.

To verify:

1. Go to Insights → Community
2. Check percentage (target: 100%)
3. Create missing files from checklist

11. Pre-Launch Checklist

Complete these tasks before making repository public or announcing to community:

Required Files

• CODE_OF_CONDUCT.md - Download from Contributor Covenant

  • Save to repository root
  • Update contact email to maintainer email

• SECURITY.md - Create in repository root:

# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 1.x.x   | :white_check_mark: |

## Reporting a Vulnerability

**DO NOT** create a public issue for security vulnerabilities.

Instead, please report security vulnerabilities via GitHub's private vulnerability reporting:

1. Go to the **Security** tab
2. Click **Report a vulnerability**
3. Fill out the form with details

Alternatively, email security concerns to: [MAINTAINER_EMAIL]

We aim to respond within 48 hours and provide a fix within 7 days for critical vulnerabilities.

## Scope

This repository contains Claude Code skills (documentation and configuration). Security concerns include:

- Exposure of API keys or secrets in skill examples
- Malicious code in skill instructions
- Dependency vulnerabilities (if any)
- Social engineering via skill content

## Out of Scope

- Issues with Claude Code itself (report to Anthropic)
- General skill usage questions (use Discussions)

Repository Configuration

• Branch protection enabled on main (see Section 3)
• Security features enabled (see Section 4)
• GitHub Actions permissions configured (see Section 5)
• Issue and PR templates tested (create test issue/PR)
• Labels created (run script from Appendix A)
• Repository description and topics set (see Section 2)
• Discussions enabled with categories (see Section 7)

Documentation Review

• CONTRIBUTING.md updated with self-containment standard reference
• README.md includes badges:

  ![GitHub](https://img.shields.io/github/license/OWNER/claude-mpm-skills)
  ![GitHub issues](https://img.shields.io/github/issues/OWNER/claude-mpm-skills)
  ![GitHub stars](https://img.shields.io/github/stars/OWNER/claude-mpm-skills)
  

• README.md includes contribution section linking to CONTRIBUTING.md
• All documentation links tested (no broken links)

CI/CD Validation

• .github/workflows/validate-skills.yml tested (create test PR)
• Self-containment validation working (check for relative paths)
• Manifest validation working (test with invalid JSON)
• Sensitive data detection working (test with fake API key)

Testing

• Create test issue using each template (verify fields work)
• Create test PR using template (verify checklist appears)
• Trigger CI workflow and verify it runs
• Test branch protection (attempt direct push to main - should fail)
• Test required reviews (verify PR cannot merge without approval)

Final Verification

• Community health at 100% (check Insights → Community)
• All required status checks configured
• CODEOWNERS file present and correct
• Repository visibility set appropriately (public vs private)

12. Post-Launch Monitoring

Week 1 (High Attention Period)

Daily tasks:

• Monitor new issues (are templates being used correctly?)
• Respond to first-time contributors within 24 hours
• Watch for CI failures on PRs
• Check Discussions for questions

Metrics to track:

• Number of issues opened
• Issue template compliance rate
• Average time to first response
• PR submission rate
• CI pass/fail rate

Month 1 (Adjustment Period)

Weekly tasks:

• Review label usage (are labels being applied correctly?)
• Identify common questions → add to FAQ or documentation
• Evaluate issue template effectiveness (missing fields?)
• Monitor community engagement in Discussions
• Review and merge Dependabot PRs

Adjust as needed:

• Refine issue templates if missing critical information
• Add new labels based on emerging patterns
• Update CONTRIBUTING.md with lessons learned
• Create discussion templates for common topics

Ongoing Maintenance

Monthly:

• Review community health score
• Audit open issues (close stale issues, update priorities)
• Update documentation based on contributor feedback
• Evaluate contributor growth (new vs repeat)
• Review CI workflow efficiency (reduce run time if possible)

Quarterly:

• Analyze contribution trends (which skills most requested?)
• Update roadmap based on community input
• Recognize top contributors (shoutouts in Discussions)
• Review and update security policy if needed
• Evaluate label taxonomy (add/remove/rename labels)

Annually:

• Complete documentation audit
• Update Code of Conduct if needed
• Review contributor guidelines for clarity
• Assess repository structure (reorganize if needed)

13. Automated CI Workflows

Current Workflow: validate-skills.yml

Located at: .github/workflows/validate-skills.yml

Current checks:

• ✅ Skill structure validation (SKILL.md, metadata.json presence)
• ✅ Manifest validation (JSON syntax)
• ✅ Sensitive data detection (API keys, secrets)

Recommended Enhancements

Enhanced Self-Containment Check

Create: .github/workflows/self-containment-check.yml

name: Self-Containment Validation

on:
  pull_request:
    paths:
      - 'toolchains/**'
      - 'universal/**'
      - 'frameworks/**'
      - 'bundled/**'

jobs:
  validate-self-containment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check for relative path dependencies
        run: |
          echo "🔍 Checking for relative path violations..."

          # Check for relative path imports in SKILL.md files
          VIOLATIONS=$(grep -r "\.\./\|\.\./" --include="SKILL.md" toolchains/ universal/ frameworks/ bundled/ 2>/dev/null || true)

          if [ -n "$VIOLATIONS" ]; then
            echo "❌ Found relative path dependencies:"
            echo "$VIOLATIONS"
            echo ""
            echo "Skills must be self-contained. See docs/SKILL_SELF_CONTAINMENT_STANDARD.md"
            exit 1
          fi

          echo "✅ No relative path dependencies found"

      - name: Check for skill dependencies
        run: |
          echo "🔍 Checking for hard skill dependencies..."

          # Look for phrases indicating dependencies
          DEPS=$(grep -r "requires.*skill\|depends on.*skill\|see.*skill" --include="SKILL.md" toolchains/ universal/ frameworks/ bundled/ 2>/dev/null || true)

          if [ -n "$DEPS" ]; then
            echo "⚠️ Potential skill dependencies found:"
            echo "$DEPS"
            echo ""
            echo "Review these references - skills should be self-contained."
            echo "Use soft references if complementary skills mentioned."
            # Warning only - don't fail build
          fi

      - name: Validate metadata.json
        run: |
          echo "🔍 Validating all metadata.json files..."

          FAILED=0
          for file in $(find toolchains/ universal/ frameworks/ bundled/ -name "metadata.json" 2>/dev/null); do
            echo "Checking $file..."
            if ! python3 -m json.tool "$file" > /dev/null 2>&1; then
              echo "❌ Invalid JSON in $file"
              FAILED=1
            fi
          done

          if [ $FAILED -eq 1 ]; then
            exit 1
          fi

          echo "✅ All metadata.json files valid"

      - name: Check for complete examples
        run: |
          echo "🔍 Checking for code example completeness..."

          # Check for common indicators of incomplete examples
          INCOMPLETE=$(grep -r "# \.\.\.\|// \.\.\.\|truncated\|abbreviated" --include="SKILL.md" toolchains/ universal/ frameworks/ bundled/ 2>/dev/null || true)

          if [ -n "$INCOMPLETE" ]; then
            echo "⚠️ Potential incomplete examples found:"
            echo "$INCOMPLETE"
            echo ""
            echo "Examples should be complete and runnable."
            # Warning only
          fi

Label Auto-Assignment

Create: .github/workflows/auto-label.yml

name: Auto-Label Issues and PRs

on:
  issues:
    types: [opened]
  pull_request:
    types: [opened]

jobs:
  auto-label:
    runs-on: ubuntu-latest
    permissions:
      issues: write
      pull-requests: write
    steps:
      - name: Label new issues
        if: github.event_name == 'issues'
        uses: actions/github-script@v7
        with:
          script: |
            // Auto-apply triage status to new issues
            await github.rest.issues.addLabels({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              labels: ['🚦 status: triage']
            });

      - name: Label skill-related PRs
        if: github.event_name == 'pull_request'
        uses: actions/github-script@v7
        with:
          script: |
            const { data: files } = await github.rest.pulls.listFiles({
              owner: context.repo.owner,
              repo: context.repo.repo,
              pull_number: context.issue.number
            });

            const labels = [];

            // Detect skill categories based on changed files
            const pathPatterns = {
              'skill: python': /toolchains\/python/,
              'skill: typescript': /toolchains\/typescript/,
              'skill: javascript': /toolchains\/javascript/,
              'skill: nextjs': /frameworks\/nextjs/,
              'skill: ai': /toolchains\/.*\/ai/,
              'skill: universal': /universal\//
            };

            for (const [label, pattern] of Object.entries(pathPatterns)) {
              if (files.some(file => pattern.test(file.filename))) {
                labels.push(label);
              }
            }

            // Check for new skills
            const hasNewSkill = files.some(file =>
              file.filename.includes('SKILL.md') && file.status === 'added'
            );

            if (hasNewSkill) {
              labels.push('🚀 type: new-skill');
            }

            // Apply labels
            if (labels.length > 0) {
              await github.rest.issues.addLabels({
                owner: context.repo.owner,
                repo: context.repo.repo,
                issue_number: context.issue.number,
                labels: labels
              });
            }

PR Size Labeling

Create: .github/workflows/pr-size.yml

name: PR Size Labeling

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  size-label:
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
    steps:
      - uses: codelytv/pr-size-labeler@v1
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          xs_label: 'effort: small'
          xs_max_size: '50'
          s_label: 'effort: small'
          s_max_size: '150'
          m_label: 'effort: medium'
          m_max_size: '400'
          l_label: 'effort: large'
          l_max_size: '800'
          xl_label: 'effort: epic'
          fail_if_xl: 'false'

Workflow Best Practices

Do:

• ✅ Keep workflows focused (one responsibility per workflow)
• ✅ Use descriptive job and step names
• ✅ Add comments explaining complex logic
• ✅ Test workflows on fork before deploying
• ✅ Use official GitHub actions when possible
• ✅ Set appropriate permissions (minimal required)

Don't:

• ❌ Store secrets in workflow files (use repository secrets)
• ❌ Run workflows on every commit (filter by path/files)
• ❌ Auto-merge PRs without review
• ❌ Grant write access to forks
• ❌ Ignore workflow security warnings

Appendix A: Label Creation Script

Save as scripts/create-labels.sh:

#!/bin/bash
# GitHub label creation script for claude-mpm-skills
# Requires: GitHub CLI (gh) - Install: https://cli.github.com/
# Usage: bash scripts/create-labels.sh

set -e

echo "🏷️  Creating labels for claude-mpm-skills..."
echo ""

# Check if gh CLI is installed
if ! command -v gh &> /dev/null; then
    echo "❌ GitHub CLI (gh) not found"
    echo "Install from: https://cli.github.com/"
    exit 1
fi

# Check if authenticated
if ! gh auth status &> /dev/null; then
    echo "❌ Not authenticated with GitHub CLI"
    echo "Run: gh auth login"
    exit 1
fi

echo "Creating Priority Labels..."
gh label create "🟥 priority: critical" --color b60205 --description "Must be fixed ASAP" --force
gh label create "🟧 priority: high" --color d93f0b --description "Blocks dependent work" --force
gh label create "🟨 priority: medium" --color fbca04 --description "Important but non-blocking" --force
gh label create "🟩 priority: low" --color cfda2c --description "Nice to have, no rush" --force

echo "Creating Status Labels..."
gh label create "🚦 status: triage" --color eeeeee --description "Needs initial review" --force
gh label create "🔍 status: needs-info" --color d4c5f9 --description "Awaiting information" --force
gh label create "🚧 status: blocked" --color 333333 --description "Cannot proceed" --force
gh label create "🏁 status: ready" --color 0e8a16 --description "Ready for implementation" --force
gh label create "👀 status: in-review" --color fbca04 --description "Under active review" --force
gh label create "⛔ status: wontfix" --color ffffff --description "Rejected/out of scope" --force
gh label create "✅ status: done" --color 1d76db --description "Completed" --force

echo "Creating Type Labels..."
gh label create "🐛 type: bug" --color d73a4a --description "Something isn't working" --force
gh label create "✨ type: enhancement" --color a2eeef --description "Improvement to existing feature" --force
gh label create "🚀 type: new-skill" --color 0075ca --description "Proposal for new skill" --force
gh label create "📖 type: documentation" --color 0075ca --description "Documentation improvements" --force
gh label create "🔧 type: tooling" --color d4c5f9 --description "CI/CD, scripts, automation" --force
gh label create "💬 type: question" --color d876e3 --description "User question" --force
gh label create "🎨 type: design" --color e99695 --description "UI/UX, repository structure" --force

echo "Creating Skill Category Labels..."
gh label create "skill: python" --color 3572A5 --description "Python skills" --force
gh label create "skill: typescript" --color 2b7489 --description "TypeScript skills" --force
gh label create "skill: javascript" --color f1e05a --description "JavaScript skills" --force
gh label create "skill: nextjs" --color 000000 --description "Next.js skills" --force
gh label create "skill: ui" --color 563d7c --description "UI/styling skills" --force
gh label create "skill: ai" --color ff6f00 --description "AI/ML skills" --force
gh label create "skill: platform" --color 89e051 --description "Platform/deployment" --force
gh label create "skill: universal" --color ededed --description "Universal skills" --force

echo "Creating Effort Labels..."
gh label create "effort: small" --color c2e0c6 --description "< 2 hours of work" --force
gh label create "effort: medium" --color fef2c0 --description "2-8 hours of work" --force
gh label create "effort: large" --color f9d0c4 --description "1-3 days of work" --force
gh label create "effort: epic" --color d93f0b --description "Multi-day or requires research" --force

echo "Creating Community Labels..."
gh label create "good first issue" --color 7057ff --description "Good for newcomers" --force
gh label create "help wanted" --color 008672 --description "Maintainer requests community help" --force
gh label create "🔒 staff only" --color d73a4a --description "Requires maintainer privileges" --force
gh label create "duplicate" --color cfd3d7 --description "Duplicate of another issue" --force
gh label create "invalid" --color e4e669 --description "Invalid issue" --force

echo "Creating Automated Labels..."
gh label create "🤖 auto: validation-failed" --color b60205 --description "CI validation checks failed" --force
gh label create "🤖 auto: sensitive-data" --color d73a4a --description "Potential credentials detected" --force
gh label create "🤖 auto: manifest-error" --color d93f0b --description "manifest.json validation failed" --force

echo ""
echo "✅ All labels created successfully!"
echo ""
echo "Total: 40 labels across 7 categories"

To use:

# Make executable
chmod +x scripts/create-labels.sh

# Run script
bash scripts/create-labels.sh

Prerequisites:

1. Install GitHub CLI: brew install gh (macOS) or see https://cli.github.com/
2. Authenticate: gh auth login
3. Run script from repository root

Appendix B: Troubleshooting

Common Issues

Issue: Branch protection not enforcing

Symptoms: PRs merge without reviews or status checks

Solutions:

1. Verify protection rule applies to main (not master or typo)
2. Check "Do not allow bypassing" is enabled
3. Confirm you're not an admin bypassing rules
4. Verify status check name matches exactly (case-sensitive)

Issue: Status checks not appearing in branch protection

Symptoms: Cannot select CI workflow in required checks

Solutions:

1. Workflow must run at least once on a PR to be selectable
2. Check workflow name matches: validate / validate
3. Verify workflow triggers on pull_request events
4. Look for workflow errors in Actions tab

Issue: Labels not applying automatically

Symptoms: Auto-label workflow not triggering

Solutions:

1. Verify workflow file in .github/workflows/ directory
2. Check workflow permissions (needs issues: write)
3. Ensure workflow triggers on correct events
4. Check Actions tab for errors
5. Verify repository allows Actions to run

Issue: Secret scanning blocking legitimate code

Symptoms: Push blocked for fake/example API keys

Solutions:

1. Use placeholders: YOUR_API_KEY, <API_KEY>, {API_KEY}
2. Mark as example in comments: # Example only - not real
3. Bypass protection if absolutely needed (not recommended)

Issue: Dependabot PRs not creating

Symptoms: No automatic dependency update PRs

Solutions:

1. Verify Dependabot is enabled in Settings → Security
2. Check for dependabot.yml configuration errors
3. Ensure repository has dependencies to update
4. Check Dependabot logs in Insights → Dependency graph

Issue: Community health checklist incomplete

Symptoms: Missing checkmarks in Insights → Community

Solutions:

1. Verify file names are exact (case-sensitive)
2. Ensure files in correct locations (root, .github/, or docs/)
3. Files must be on default branch (main)
4. Wait 5-10 minutes for GitHub to detect new files
5. Hard refresh browser cache

Additional Resources

Official GitHub Documentation

• About protected branches
• Configuring issue templates
• Managing labels
• [Securing your repos

…(truncated)