feat(ci): implement comprehensive GitHub automation workflows
Implemented full GitHub automation system from claude-code-skills-factory with project-specific configuration for claude-skills repository. ## New Workflows - **ci-quality-gate.yml**: Automated linting, testing, and security checks - **claude-code-review.yml**: Enhanced with kill switch and bypass mechanisms - **pr-issue-auto-close.yml**: Auto-close linked issues when PRs merge - **smart-sync.yml**: Bidirectional sync between issues and project board ## Configuration Files - **WORKFLOW_KILLSWITCH**: Emergency workflow disable capability - **branch-protection-config.json**: Branch protection settings - **commit-template.txt**: Standardized commit message template - **AUTOMATION_SETUP.md**: Complete setup and configuration guide ## Templates - **pull_request_template.md**: Enhanced with security and quality checklists ## Key Features ✅ AI-powered code reviews with Claude ✅ Automatic issue closure on PR merge ✅ Bidirectional issue ↔ project board sync ✅ Quality gates (YAML lint, Python syntax, security audit) ✅ Kill switch for emergency workflow disable ✅ Rate limit protection with circuit breakers ✅ 10-second debouncing to prevent sync loops ## Project Configuration - Repository: alirezarezvani/claude-skills - Project Number: 9 - Status: Ready for PROJECTS_TOKEN configuration ## Testing Workflows validated with yamllint and ready for deployment. See .github/AUTOMATION_SETUP.md for complete setup instructions.
This commit is contained in:
Reza Rezvani
325
.github/AUTOMATION_SETUP.md
vendored
Normal file
325
.github/AUTOMATION_SETUP.md
vendored
Normal file
@@ -0,0 +1,325 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```markdown
|
||||
## 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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 ⚙️
|
||||
Reference in New Issue
Block a user