claude-skills-reference/.github/AUTOMATION_SETUP.md

GitHub Automation Setup Guide

Repository: claude-skills Project Number: 9 Status: ⚙️ Configuration Required

---

Overview

This repository includes AI-powered GitHub automation with:

• ✅ Claude Code Review - Automatic PR reviews
• ✅ Auto-Close Issues - PRs auto-close linked issues when merged
• ✅ Smart Sync - Bidirectional issue ↔ project board synchronization
• ✅ Quality Gates - Automated linting, testing, security checks
• ✅ Kill Switch - Emergency workflow disable capability

---

Quick Start (15 minutes)

1. Create Required Secrets

You need 2 secrets for full automation:

✅ CLAUDE_CODE_OAUTH_TOKEN (Already Configured)

This secret is already set up for Claude Code reviews.

⚠️ PROJECTS_TOKEN (Required for Project Board Sync)

Create Personal Access Token:

1. Go to: https://github.com/settings/tokens/new
2. Configure:
   • Note: "Claude Skills Project Board Access"
   • Expiration: 90 days (recommended)
   • Select scopes:
     • ✅ repo (Full control of private repositories)
     • ✅ project (Full control of projects)
3. Click "Generate token"
4. Copy the token (you won't see it again!)

Add to Repository:

1. Go to: https://github.com/alirezarezvani/claude-skills/settings/secrets/actions
2. Click "New repository secret"
3. Name: PROJECTS_TOKEN
4. Value: [Paste your token]
5. Click "Add secret"

---

2. Create Project Board Labels

Run these commands to create all required labels:

# Status Labels (6)
gh label create "status: triage" --color "fbca04" --description "To Triage column" --repo alirezarezvani/claude-skills
gh label create "status: backlog" --color "d4c5f9" --description "Backlog column" --repo alirezarezvani/claude-skills
gh label create "status: ready" --color "0e8a16" --description "Ready column" --repo alirezarezvani/claude-skills
gh label create "status: in-progress" --color "1d76db" --description "In Progress column" --repo alirezarezvani/claude-skills
gh label create "status: in-review" --color "d876e3" --description "In Review column" --repo alirezarezvani/claude-skills
gh label create "status: done" --color "2ea44f" --description "Done column" --repo alirezarezvani/claude-skills

# Priority Labels (4)
gh label create "P0" --color "b60205" --description "Critical priority" --repo alirezarezvani/claude-skills
gh label create "P1" --color "d93f0b" --description "High priority" --repo alirezarezvani/claude-skills
gh label create "P2" --color "fbca04" --description "Medium priority" --repo alirezarezvani/claude-skills
gh label create "P3" --color "0e8a16" --description "Low priority" --repo alirezarezvani/claude-skills

# Type Labels (already exist - verify)
# bug, feature, documentation, enhancement, etc.

---

3. Configure Project Board

Your project board columns must match these exact names:

1. To triage
2. Backlog
3. Ready
4. In Progress
5. In Review
6. Done

Verify Configuration:

1. Go to: https://github.com/users/alirezarezvani/projects/9
2. Check column names match exactly (case-sensitive)
3. Ensure "Status" field exists

---

4. Test the Setup

Test 1: Create Test Issue

gh issue create \
  --title "Test: Automation Setup" \
  --body "Testing GitHub automation workflows" \
  --label "status: triage" \
  --repo alirezarezvani/claude-skills

Expected Results:

• ✅ Issue created
• ✅ Auto-added to project board (column: "To triage")
• ✅ Label synced

Test 2: Change Issue Status

# Get the issue number from step 1, then:
gh issue edit ISSUE_NUMBER --add-label "status: in-progress" --repo alirezarezvani/claude-skills

Expected Results:

• ✅ Issue moved to "In Progress" on project board
• ✅ Old status label removed
• ✅ New status label applied

Test 3: Create Test PR

# Create a branch
git checkout -b test/automation-setup
echo "# Test" > TEST.md
git add TEST.md
git commit -m "test: verify automation"
git push origin test/automation-setup

# Create PR that fixes the test issue
gh pr create \
  --title "test: Verify automation workflows" \
  --body "Fixes #ISSUE_NUMBER" \
  --repo alirezarezvani/claude-skills

Expected Results:

• ✅ Claude review triggers (check Actions tab)
• ✅ CI Quality Gate runs
• ✅ When merged, issue auto-closes
• ✅ Project board updates to "Done"

---

Active Workflows

Workflow	Trigger	Status
claude-code-review.yml	PR opened/updated	✅ Active
pr-issue-auto-close.yml	PR merged	✅ Active
smart-sync.yml	Issue/board changes	⚠️ Requires PROJECTS_TOKEN
ci-quality-gate.yml	PR opened/updated	✅ Active

---

Emergency Procedures

🚨 Disable All Workflows

If something goes wrong:

echo "STATUS: DISABLED" > .github/WORKFLOW_KILLSWITCH
git add .github/WORKFLOW_KILLSWITCH
git commit -m "emergency: Disable workflows"
git push origin main --no-verify

All workflows check this file and exit immediately if disabled.

✅ Re-enable Workflows

echo "STATUS: ENABLED" > .github/WORKFLOW_KILLSWITCH
git commit -am "chore: Re-enable workflows"
git push

---

Usage Examples

Auto-Close Issues with PR

In your PR description:

## Summary
Fixed the authentication bug

## Related Issues
Fixes #123
Closes #456

When merged → Issues #123 and #456 automatically close with comment linking to PR.

Sync Issue Status

Option A - Update Label:

gh issue edit 123 --add-label "status: in-review"

→ Moves to "In Review" on project board

Option B - Update Board:

Drag issue to "In Review" column on project board

→ Adds "status: in-review" label to issue

---

Troubleshooting

Smart Sync Not Working

Problem: Labels not syncing with project board

Check:

gh secret list --repo alirezarezvani/claude-skills | grep PROJECTS_TOKEN

Solution: If missing, add PROJECTS_TOKEN (see Step 1 above)

Claude Review Not Running

Problem: No review comment on PR

Check:

gh run list --workflow=claude-code-review.yml --limit 5 --repo alirezarezvani/claude-skills

Solutions:

• Verify CLAUDE_CODE_OAUTH_TOKEN exists
• Check workflow logs for errors
• Re-run workflow from Actions tab

Rate Limits

Check current limits:

gh api rate_limit --jq '.resources.core.remaining, .resources.graphql.remaining'

Rate Limit Info:

• REST API: 5,000/hour
• GraphQL: 5,000/hour
• Workflows require 50+ remaining before executing

---

Maintenance

Weekly

# Check failed runs
gh run list --status failure --limit 10 --repo alirezarezvani/claude-skills

# Verify secrets valid
gh secret list --repo alirezarezvani/claude-skills

Quarterly

# Regenerate PROJECTS_TOKEN (expires every 90 days)
# 1. Create new token with same scopes
# 2. Update repository secret
# 3. Test with a sync operation

---

Security Notes

4-Layer Security Model:

1. GitHub Permissions - Only team members trigger workflows
2. Tool Restrictions - Allowlist specific commands only
3. Token Scoping - Minimal permissions (repo + project)
4. Branch Protection - Required reviews, status checks

Kill Switch: Emergency disable capability (WORKFLOW_KILLSWITCH file)

---

Next Steps

1. ✅ Create PROJECTS_TOKEN secret
2. ✅ Create all required labels
3. ✅ Verify project board columns
4. ✅ Test with sample issue and PR
5. ✅ Monitor first few workflow runs
6. ✅ Document any project-specific customizations

---

Support

Documentation:

• This setup guide
• Individual workflow files in .github/workflows/
• Factory reference: https://github.com/alirezarezvani/claude-code-skills-factory

Getting Help:

• Create issue with question label
• Check workflow logs: gh run view RUN_ID --log
• Review troubleshooting section above

---

Last Updated: 2025-11-04 Status: Ready for configuration ⚙️