GitHub Automation System

Complete CI/CD & workflow automation for Claude Code Tresor

Version: 1.0.0 Created: November 4, 2025 Status: Production Ready ✅

Overview

Claude Code Tresor uses a comprehensive GitHub Actions automation system for quality assurance, branch protection, AI-powered code review, security audits, and release management.

Automation Goals

Quality Assurance - Automated testing, linting, security scans
Branch Protection - Enforce naming conventions and conventional commits
Code Review - AI-powered review with Claude Code
Release Management - Automated versioning and release notes
Developer Experience - Fast feedback, clear errors, bypass mechanisms

Core Workflows

1. Commit & Branch Guard

File: .github/workflows/ci-commit-branch-guard.yml

Purpose: Enforce branch naming conventions and conventional commits

Triggers:

Pull request (opened, synchronize, reopened, ready_for_review)
Manual dispatch

Validates:

✅ Branch naming: feat/, fix/, docs/, chore/, refactor/, test/, build/, ci/, perf/, style/, hotfix/, release/
✅ Conventional commits using commitlint
✅ Automated branches: dependabot/, renovate/

Failure conditions:

❌ Branch name doesn't match pattern
❌ Commit messages don't follow conventional commit format

2. CI Quality Gate

File: .github/workflows/ci-quality-gate.yml

Purpose: Comprehensive quality checks before merge

Triggers:

Pull request (opened, synchronize, reopened, ready_for_review)
Manual dispatch

Quality checks:

YAML Linting - Validates workflow YAML syntax
GitHub Workflow Schema - Ensures workflows match GitHub schema
YAML Frontmatter - Validates SKILL.md and agent .md frontmatter
Markdown Links - Validates README links

Timeout: 25 minutes Concurrency: Cancels previous runs on new commits

3. Claude Code Review

File: .github/workflows/claude-code-review.yml

Purpose: AI-powered code review using Claude Code

Triggers:

Pull request (opened, synchronize)

Review criteria:

💡 Code quality and best practices
🐛 Potential bugs or issues
⚡ Performance considerations
🔐 Security concerns
🧪 Test coverage

Bypass mechanisms:

PR title markers: [EMERGENCY], [SKIP REVIEW], [HOTFIX]
PR labels: emergency, skip-review, hotfix
Kill switch: .github/WORKFLOW_KILLSWITCH

Fallback: Posts notice if quota exceeded or timeout

4. Security Audit

File: .github/workflows/security-audit.yml

Purpose: AI-powered security review using Claude Code

Triggers:

Pull request (opened, synchronize, reopened, ready_for_review)

Security focus:

🔒 OWASP Top 10 vulnerabilities
🔒 Secrets exposure (API keys, tokens)
🔒 Supply chain risks
🔒 Dangerous command patterns
🔒 LLM agent hardening

Output: PR comment with severity summary and actionable findings

Bypass: Uses kill switch (.github/WORKFLOW_KILLSWITCH)

5. Release Orchestrator

File: .github/workflows/release-orchestrator.yml

Purpose: Automated release creation with version tagging

Triggers:

Manual dispatch (workflow_dispatch)

Inputs:

version - Semantic version (e.g., v1.4.0)
target - Branch/commit to release from (default: main)

Process:

Prepare: Gather commits since last tag, generate release notes
Publish: Create annotated git tag, draft GitHub Release

Outputs:

Annotated git tag
Draft GitHub Release with auto-generated notes
Release notes include commit history with timestamps

Branching Strategy

Branch Hierarchy

main (production) - Protected, requires PR approval
  ↑
dev (development) - Protected, requires status checks
  ↑
feature/* (feature branches) - Follows naming conventions

Branch Naming Rules

Allowed prefixes:

feat/ - New features
fix/ - Bug fixes
docs/ - Documentation
chore/ - Maintenance
refactor/ - Code refactoring
test/ - Tests
build/ - Build system
ci/ - CI/CD changes
perf/ - Performance
style/ - Code style
hotfix/ - Emergency fixes
release/ - Release prep

Automated branches:

dependabot/ - Dependabot PRs
renovate/ - Renovate PRs

Conventional Commits

Required Format

<type>(<scope>): <subject>

<body>

<footer>

Valid Types

feat - New feature
fix - Bug fix
docs - Documentation
style - Formatting
refactor - Refactoring
perf - Performance
test - Tests
build - Build system
ci - CI/CD
chore - Maintenance
revert - Revert

Examples

feat(workflows): add GitHub Actions automation system

Implement 5 core workflows: branch guard, quality gate,
Claude code review, security audit, and release orchestrator.

Based on claude-code-skills-factory proven patterns.

fix(quality-gate): validate YAML frontmatter in skills and agents

Add Python YAML validation for SKILL.md and agent .md files
to catch syntax errors before merge.

docs(automation): add comprehensive GitHub automation guide

Document all workflows, branching strategy, conventional commits,
and troubleshooting procedures.

Required Configuration

GitHub Secrets

1. CLAUDE_CODE_OAUTH_TOKEN

Status: Required for AI workflows
Purpose: Claude Code AI integration

How to get:

# In Claude Code CLI:
/install-github-app

# Follow OAuth flow
# Copy token to: GitHub → Settings → Secrets → Actions → New repository secret

2. GITHUB_TOKEN

Status: Automatic
Purpose: GitHub API access
Note: Provided automatically by GitHub Actions

Kill Switch

File: .github/WORKFLOW_KILLSWITCH

STATUS: ENABLED
REASON: Normal operations
LAST_UPDATED: 2025-11-04

To disable workflows:

STATUS: DISABLED
REASON: Testing kill switch
LAST_UPDATED: 2025-11-04

Affects: Claude Code Review, Security Audit

Workflow Execution

On Pull Request

Automated workflows:

Branch name validation - Enforces naming conventions
Commit message validation - Enforces conventional commits
Quality checks - YAML linting, schema validation, frontmatter validation
Claude Code review - AI-powered code review (requires token)
Security audit - AI-powered security scanning (requires token)

Execution time: ~5-10 minutes total (parallel execution)

On Manual Dispatch

Release Orchestrator:

Navigate to: Actions → Release Orchestrator → Run workflow
Enter version: v3.0.0-beta.1
Enter target branch: main (or dev for testing)
Click "Run workflow"

Result:

Git tag created
Draft GitHub Release with auto-generated notes

Bypass Mechanisms

Emergency Situations

Use when: Critical hotfix needed immediately

Methods:

1. PR Title Markers:

[EMERGENCY] fix: critical security patch
[HOTFIX] fix: production outage
[SKIP REVIEW] chore: urgent dependency update

2. PR Labels: Add label: emergency, hotfix, or skip-review

3. Kill Switch: Edit .github/WORKFLOW_KILLSWITCH:

STATUS: DISABLED
REASON: Emergency hotfix - restoring service
LAST_UPDATED: 2025-11-04

Result: Review workflows exit early, post notice, other checks still run

Testing Workflows

Phase 1: Local Validation

# 1. Check workflow YAML syntax
yamllint .github/workflows

# 2. Validate workflow schemas
npx check-jsonschema --schema github-workflow .github/workflows/*.yml

# 3. Check SKILL.md YAML frontmatter
find skills -name "SKILL.md" | while read file; do
  python -c "import yaml; yaml.safe_load(open('$file').read().split('---')[1])"
done

# 4. Check commit message format
npx commitlint --from HEAD~1 --to HEAD

Phase 2: GitHub Actions Testing

Test 1: Commit & Branch Guard

# Create feature branch with valid name
git checkout -b feat/test-workflows

# Create commit with conventional message
git commit -m "feat(workflows): test GitHub Actions automation

This commit tests the workflow automation system."

# Push and create PR
git push -u origin feat/test-workflows

# Expected: ✅ Branch name passes, ✅ Commit message passes

Test 2: Quality Gate

# Quality gate automatically runs on PR
# Check: Actions tab → CI Quality Gate workflow

# Expected checks:
# ✅ YAML linting passes
# ✅ Workflow schema validation passes
# ✅ SKILL.md frontmatter validation passes
# ✅ README markdown links pass

Test 3: Claude Code Review (Requires Token)

# Configure CLAUDE_CODE_OAUTH_TOKEN first
# PR automatically triggers Claude review

# Expected:
# ⏳ Claude reviews code
# 💬 Posts review comment on PR
# OR ⚠️ Posts fallback notice if quota exceeded

Test 4: Release Orchestrator

# Manual workflow dispatch from Actions tab
# Inputs: version: v3.0.0-beta.1, target: dev

# Expected:
# ✅ Git tag created: v3.0.0-beta.1
# ✅ Release notes generated from commits
# ✅ Draft GitHub Release created

Branch Protection Rules

Main Branch

Configure: Repository → Settings → Branches → Add rule

Rules:

✅ Require pull request reviews (1 reviewer recommended)
✅ Require status checks before merging:
- CI Quality Gate
- Commit & Branch Guard
✅ Require branches to be up to date before merging
✅ Require conversation resolution before merging
❌ No force pushes
❌ No deletions

Dev Branch

Rules:

✅ Require pull request reviews (optional)
✅ Require status checks before merging:
- CI Quality Gate
- Commit & Branch Guard
✅ Require branches to be up to date
⚠️ Allow force pushes (for cleanup)
❌ No deletions

Troubleshooting

Workflow Fails: Branch Name Invalid

Error: Branch name 'my-feature' doesn't match required pattern

Solution:

# Rename branch with valid prefix
git branch -m my-feature feat/my-feature
git push origin :my-feature feat/my-feature

Workflow Fails: Commit Message Invalid

Error: Commit message doesn't follow conventional commit format

Solution:

# Amend commit message
git commit --amend -m "feat: add my feature

Detailed description here."

# Force push (only if branch not shared)
git push --force-with-lease

Claude Review Skipped: Quota Exceeded

Message: Claude Code review skipped - quota exceeded or API unavailable

Solutions:

Wait for quota reset (usually daily)
Manual review - Review code manually
Bypass if urgent - Use [EMERGENCY] in PR title

Kill Switch Not Working

Problem: Workflows still running despite kill switch set to DISABLED

Check:

Verify .github/WORKFLOW_KILLSWITCH file exists
Check STATUS line is exactly: STATUS: DISABLED
Commit and push kill switch file
Create new PR to test

Quality Gate Fails: YAML Frontmatter

Error: YAML frontmatter validation failed for skills/code-reviewer/SKILL.md

Solutions:

# Check YAML syntax manually
python -c "
import yaml
content = open('skills/code-reviewer/SKILL.md').read()
yaml_part = content.split('---')[1]
try:
    yaml.safe_load(yaml_part)
    print('✅ Valid YAML')
except yaml.YAMLError as e:
    print(f'❌ YAML Error: {e}')
"

# Common issues:
# - Incorrect indentation (use 2 spaces)
# - Missing quotes around special characters
# - Extra spaces after colons

Implementation Summary

Files Created

Workflow Files (.github/workflows/):

✅ ci-commit-branch-guard.yml (79 lines)
✅ ci-quality-gate.yml (88 lines)
✅ claude-code-review.yml (134 lines)
✅ security-audit.yml (85 lines)
✅ release-orchestrator.yml (121 lines)

Configuration Files: 6. ✅ commitlint.config.js 7. ✅ .github/WORKFLOW_KILLSWITCH

Documentation: 8. ✅ documentation/workflows/github-automation.md (this file)

Benefits Achieved

Developer Experience

✅ Automated quality checks - Catch issues before merge ✅ AI-powered reviews - Claude Code provides expert feedback ✅ Security scanning - Proactive vulnerability detection ✅ Consistent commits - Enforced conventional commit format ✅ Easy releases - One-click version tagging

Code Quality

✅ YAML validation - No syntax errors in skills/agents ✅ Schema compliance - Workflows match GitHub requirements ✅ Documentation checks - Valid markdown links ✅ Security first - OWASP and LLM-specific checks

Team Efficiency

✅ Fast feedback - Workflows run in parallel (<10 min total) ✅ Clear errors - Actionable error messages ✅ Emergency bypasses - No blockers in critical situations ✅ Automated releases - Consistent versioning

FilesExpand file tree

github-automation.md

Latest commit

History

github-automation.md

File metadata and controls

GitHub Automation System

Overview

Automation Goals

Core Workflows

1. Commit & Branch Guard

2. CI Quality Gate

3. Claude Code Review

4. Security Audit

5. Release Orchestrator

Branching Strategy

Branch Hierarchy

Branch Naming Rules

Conventional Commits

Required Format

Valid Types

Examples

Required Configuration

GitHub Secrets

Kill Switch

Workflow Execution

On Pull Request

On Manual Dispatch

Bypass Mechanisms

Emergency Situations

Testing Workflows

Phase 1: Local Validation

Phase 2: GitHub Actions Testing

Branch Protection Rules

Main Branch

Dev Branch

Troubleshooting

Workflow Fails: Branch Name Invalid

Workflow Fails: Commit Message Invalid

Claude Review Skipped: Quota Exceeded

Kill Switch Not Working

Quality Gate Fails: YAML Frontmatter

Implementation Summary

Files Created

Benefits Achieved

Developer Experience

Code Quality

Team Efficiency

Related Documentation