ilkayurlu

GitHub Workflow Blueprint

Production-Ready GitHub Actions Automation Workflow with Claude Code

License: MIT GitHub Actions Claude Code Version Phase

Transform your development workflow from planning to deployment in under 5 minutes. A comprehensive, production-ready blueprint that combines GitHub Actions with Claude Code for intelligent, automated workflows.

🎯 What Is This?

This repository provides a complete, copy-paste and production-ready blueprint for automating your entire GitHub workflow using GitHub Actions and Claude Code. From converting plans to issues, creating branches, running quality checks, to deploying to production—everything is automated, intelligent, and production-ready. This helps you to keep the context of your tasks preserved in an efficient way. You have installation script available to run through the installation routine and chose your suitable wokrflow.

Perfect for: Solo developers, small teams, and enterprises looking to streamline their development workflow with AI-powered automation.

✨ Key Features

🚀 Quick Start

Get up and running in 3 commands:

# 1. Clone this blueprint into your project
git clone https://github.com/alirezarezvani/claude-code-github-workflow.git .github-blueprint
cd .github-blueprint

# 2. Run the interactive setup wizard
./setup/wizard.sh

# 3. Verify everything is working
./setup/validate.sh

That’s it! Your repository now has:

Next Steps:

📋 What’s Included

GitHub Actions Workflows (8)

  1. bootstrap.yml - One-time repository setup (labels, validation)
  2. reusable-pr-checks.yml - DRY quality checks (lint, test, typecheck)
  3. pr-into-dev.yml - Feature PR validation with quality gates
  4. dev-to-main.yml - Release gates with smoke tests
  5. claude-plan-to-issues.yml - Convert Claude plans to GitHub issues (max 10)
  6. create-branch-on-issue.yml - Auto-create branches from ready issues
  7. pr-status-sync.yml - Sync PR lifecycle with issue status
  8. release-status-sync.yml - Close issues on production deployment

Slash Commands (8)

  1. /blueprint-init - Interactive setup wizard
  2. /plan-to-issues - Convert plan JSON to GitHub issues
  3. /commit-smart - Smart commit with quality checks + secret detection
  4. /create-pr - Create PR with proper issue linking
  5. /review-pr - Comprehensive Claude-powered code review
  6. /release - Production release management with changelog
  7. /sync-status - Bidirectional issue/board synchronization
  8. /kill-switch - Emergency workflow disable mechanism

Autonomous Agents (4)

  1. blueprint-setup - Autonomous setup wizard with error recovery
  2. plan-converter - Intelligent plan parser with priority calculation
  3. quality-orchestrator - Comprehensive quality gate manager
  4. workflow-manager - Master automation orchestrator

Composite Actions (5)

Reusable building blocks for DRY workflows:

Configuration Templates (6)

Professional templates for consistency:

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                    User Interface Layer                          │
│        (8 Slash Commands + Interactive Wizard)                   │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    Automation Layer                              │
│        (4 Autonomous Agents + 5 Composite Actions)               │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    Workflow Layer                                │
│        (8 GitHub Actions Workflows + Projects v2 Sync)           │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                    Foundation Layer                              │
│        (Git + GitHub + Claude Code v1 GA + Project Board)        │
└─────────────────────────────────────────────────────────────────┘

Complete Data Flow

graph TD
    A[Claude Plan JSON] -->|claude-plan-to-issues.yml| B[GitHub Issues]
    B -->|Labels: claude-code + status:ready| C[Auto-create Branch]
    C -->|create-branch-on-issue.yml| D[Feature Branch]
    D -->|Developer commits| E[Create PR to dev]
    E -->|pr-into-dev.yml| F{Quality Checks}
    F -->|Pass| G[Merge to dev]
    F -->|Fail| E
    G -->|pr-status-sync.yml| H[Issues: To Deploy]
    H -->|Create PR: dev → main| I[Release Gates]
    I -->|dev-to-main.yml| J{Release Checks}
    J -->|Pass| K[Merge to main]
    J -->|Fail| I
    K -->|release-status-sync.yml| L[Close Issues ✅]
    L -->|Optional| M[Create GitHub Release]

See Architecture Documentation for detailed system design.

🎨 Branching Strategies

Choose the strategy that fits your team:

Simple (Small Teams)

feature/* → main
fix/* → main
hotfix/* → main

feature/* → dev → main
fix/* → dev → main
hotfix/* → dev → main

Complex (Enterprise)

feature/* → dev → staging → main
fix/* → dev → staging → main
hotfix/* → staging → main (fast-track)

The blueprint supports all three strategies out of the box. Choose during setup.

🔀 Branch Flow Rules

The Release to Main workflow enforces the following rules:

Standard Flow (Required for Most Branches)

feature/* → dev → main
fix/* → dev → main
test/* → dev → main

All feature, fix, and test branches must merge to dev first, then dev merges to main.

Special Exceptions (Direct to Main)

Pattern Purpose Use Case
dev Production releases Standard release flow (only dev can merge to main)
release/* Emergency hotfixes Critical fixes bypassing dev (e.g., release/1.0.1-security)
dependabot/* Dependency updates Automated dependency update PRs

Example:

# Standard flow (most common)
git checkout -b feature/new-feature
git push origin feature/new-feature
# Create PR: feature/new-feature → dev
# After merge, create PR: dev → main

# Emergency hotfix (rare)
git checkout -b release/1.0.1-security-patch
git push origin release/1.0.1-security-patch
# Create PR: release/1.0.1-security-patch → main (bypasses dev)

Important: Attempting to merge feature/, fix/, or test/* branches directly to main will fail validation.

🔒 Security & Safety

Built-in protections ensure safe, reliable automation:

📚 Documentation

🌐 Documentation Sites

→ 📖 Full Documentation Site - Modern docs with search & navigation → 📝 GitHub Wiki - Quick reference & community docs

Both sites auto-update from the docs/ folder on every commit to main.

Getting Started

Reference

Advanced

Technical Reference

📊 Success Metrics

After implementing this blueprint:

🛠️ Requirements

Minimum Requirements:

Optional:

🚦 Getting Help

Common Issues

Problem: “gh command not found” Solution: Install GitHub CLI: brew install gh (macOS) or see GitHub CLI docs

Problem: “PROJECT_URL not set” Solution: Run /blueprint-init to configure project board URL

Problem: “Workflow failed” Solution: Check recent runs: gh run list --limit 5 and view logs

Problem: “ANTHROPIC_API_KEY not set” Solution: Add your API key to repository secrets

See Troubleshooting Guide for more solutions.

Support

🤝 Contributing

Contributions are welcome! This is a blueprint designed to be customized and extended.

How to Contribute

  1. Fork this repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Areas for Contribution

Code of Conduct

Be respectful, inclusive, and constructive. See CODE_OF_CONDUCT.md for details.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

Attribution

This blueprint uses and extends:

Built with Claude Code v1 GA. All Claude Code features require an Anthropic API key.

🌟 Why Use This Blueprint?

Instead of spending weeks configuring workflows, get a production-ready system in 5 minutes.

This blueprint eliminates:

And provides:

Project Status

Total: 70 deliverables (~33,000 lines of production-ready code)

Roadmap

Acknowledgments

Connect

**⭐ If this blueprint helps you, please give it a star! ⭐** **Made with ❤️ by [Alireza Rezvani](https://github.com/alirezarezvani)** *Empowering developers with world-class automation* 🚀 Assisted By [Claude Code](https://claude.com/claude-code)