Welcome! This repository contains 5 comprehensive guides covering GitHub Actions from basic to advanced levels. Each guide includes theory, practical examples, troubleshooting, and best practices.
Learn how to create and use composite actions (reusable step bundles).
What You'll Learn:
- ✅ Basic concepts and folder structure
- ✅ Creating your first composite action
- ✅ Input types and error handling
- ✅ Advanced patterns (multi-shell, caching, security)
- ✅ Performance optimization
- ✅ Troubleshooting guide
Level: Beginner → Advanced
Use This When: You want to create reusable step bundles within a single repository.
Understand how to orchestrate workflows using parent-child relationships.
What You'll Learn:
- ✅ Workflow_call basics for beginners
- ✅ Creating parent and child workflows
- ✅ Matrix strategies (basic to dynamic)
- ✅ Conditional execution patterns
- ✅ Error handling and retry logic
- ✅ Dependency management
- ✅ Performance optimization
- ✅ Advanced patterns
Level: Beginner → Advanced
Use This When: You want to organize complex pipelines into manageable pieces.
Master reusable workflows that can be called from multiple workflows.
What You'll Learn:
- ✅ Differences: Composite Actions vs Reusable Workflows
- ✅ Calling strategies (local, external, version pinning)
- ✅ Passing complex data (JSON, arrays, artifacts)
- ✅ Versioning strategies
- ✅ Security considerations
- ✅ Advanced patterns
Level: Intermediate → Advanced
Use This When: You want to create workflows shared across multiple repositories.
Create a central repository of reusable composite actions.
What You'll Learn:
- ✅ Complete repository setup guide
- ✅ Your 5 actions explained (ACR Login, Build, Push, Backup, Cleanup)
- ✅ Versioning & tagging best practices
- ✅ Documentation standards
- ✅ Security & secrets management
- ✅ Breaking changes management
Level: Intermediate → Advanced
Use This When: You have multiple teams sharing common actions.
Complete guide to organizing GitHub Actions for multiple teams.
What You'll Learn:
- ✅ 3-team architecture and responsibilities
- ✅ Team communication patterns
- ✅ Conflict resolution strategies
- ✅ Monitoring & alerting
- ✅ Rollback strategies
- ✅ Performance metrics tracking
Level: Intermediate → Advanced
Use This When: You have 3+ teams with different responsibilities.
This repository covers 5 comprehensive methods for building workflows with GitHub Actions:
| # | Method | Basics | Intermediate | Advanced | Best For | Complexity |
|---|---|---|---|---|---|---|
| 1 | Composite Actions | Single repo reusable steps | Input/output handling | Conditional logic, error handling | Small teams, single repo | 🟢 Low |
| 2 | Parent-Child Workflows | Basic orchestration | Matrix strategies, conditionals | Fan-out/fan-in, dynamic matrices | Complex pipelines, parallel jobs | 🟡 Medium |
| 3 | Reusable Workflows | Call external workflows | Versioning, secret passing | Complex chaining, JSON data | Multi-repo setups | 🟡 Medium |
| 4 | Shared Composite Actions | Centralized action repo | Version management | Security, usage monitoring | Enterprise, 5-10 teams | 🔴 High |
| 5 | Multi-Team Setup | Team separation | Artifact sharing, dispatch | Rollback, monitoring, gates | Large orgs, 10+ teams | 🔴 High |
Recommended: Composite Actions
Why:
✅ Easiest to understand and implement
✅ Works within single repository
✅ No external dependencies
✅ Quick feedback loop for learning
✅ Perfect for first reusable components
Recommended: Parent-Child Workflows
Why:
✅ Orchestrate complex pipelines
✅ Manage dependencies between jobs
✅ Matrix strategies for parallelization
✅ Still manageable complexity
✅ Good for growing teams
Recommended: Reusable Workflows
Why:
✅ Share workflows across repos
✅ Better code organization
✅ Versioning support
✅ Reduced duplication
✅ Team collaboration friendly
Recommended: Shared Composite Actions
Why:
✅ Centralized action repository
✅ Version control for actions
✅ Breaking changes management
✅ Security governance
✅ Scaling well with multiple teams
Recommended: Multi-Team Setup + Shared Actions
Why:
✅ Complete team separation
✅ Inter-team communication
✅ Approval gates and reviews
✅ Monitoring and alerting
✅ Rollback strategies
✅ Audit trails
Recommended Setup: Shared Composite Actions ✓ YOU ARE HERE
├── ACR Login action (centralized auth)
├── Build action (reusable across services)
├── Push action (consistent tagging)
├── Backup action (disaster recovery)
└── Cleanup action (cost optimization)
Why This Works:
✅ Multiple services share same actions
✅ Consistent Docker build standards
✅ Centralized registry management
✅ Easy to add new microservices
✅ Team collaboration enabled
Next Step: Add Multi-Team Setup for
- Separate build/deploy/maintain teams
- Monitoring and alerting
- Approval gates
Recommended: Multi-Team Setup + Shared Actions
├── Build Team: Builds & pushes all services
├── Deploy Team: Kubernetes/ACI deployments
├── Maintain Team: Monitoring & cleanup
└── Shared Actions: Common operations
Team Responsibilities:
Build Team:
- Runs on code push
- Builds all services
- Pushes to registry
- Creates artifacts
Deploy Team:
- Manual trigger
- Pulls artifacts
- Updates environments
- Runs tests
Maintain Team:
- Scheduled cleanup
- Backup tags
- Monitor resources
- Cost optimization
Communication:
Build → Deploy via artifacts & dispatch
Deploy → Maintain via status events
Maintain → Build via notifications
Benefits:
✅ Clear responsibilities
✅ Parallel independent work
✅ Separate concerns
✅ Easy team scaling
Recommended: Parent-Child Workflows + Reusable
├── Parent: Main orchestrator
├── Child: Build, test, deploy
├── Reusable: Shared test workflows
└── Composite: Lint, format actions
Use When:
✅ 1-3 developers
✅ Single application
✅ Simple CI/CD
✅ Learning GitHub Actions
Can Scale To: Reusable Workflows (multi-repo)
Recommended: Parent-Child + Composite Actions
├── Parent: Pipeline orchestration
├── Child: Data validation, model training
├── Composite: ML-specific actions
└── Shared: Common utilities
Typical Pipeline:
1. Data Validation (composite action)
2. Feature Engineering (child workflow)
3. Model Training (parent orchestrates)
4. Evaluation (composite action)
5. Deployment (conditional child)
Benefits:
✅ Clear pipeline stages
✅ Reusable ML components
✅ Experiment tracking
✅ Easy to add experiments
| Scenario | Method | Reasoning |
|---|---|---|
| First GitHub Actions project | Composite Actions | Simplest, quickest to learn |
| Share steps within single repo | Composite Actions | Built-in, no setup |
| Orchestrate multiple jobs | Parent-Child Workflows | Natural job orchestration |
| Complex job dependencies | Parent-Child Workflows | Dependency management |
| Share workflows across repos | Reusable Workflows | Designed for multi-repo |
| 3-5 teams, centralized actions | Shared Composite Actions | Current setup! |
| 5-10 teams, growing org | Shared Composite Actions + planning | Scale to Multi-Team |
| 10+ teams, large org | Multi-Team Setup | Full team separation |
| Need approval gates | Multi-Team Setup | Built-in review process |
| Cost optimization critical | Shared Actions + Cleanup | Centralized control |
| Security critical | Shared Actions + OIDC | Centralized auth |
| Disaster recovery required | Shared Actions + Backup | Built-in backup |
| Multiple microservices | Shared Actions + Parent-Child | Reusable + orchestration |
✅ PHASE 1 (COMPLETED): Composite Actions
├─ Created 5 basic actions
├─ Used within docker repo
├─ Tested and documented
└─ Learning complete
✅ PHASE 2 (COMPLETED): Shared Composite Actions
├─ Created github-actions repo
├─ Versioned actions
├─ Referenced from docker repo
└─ Set up OIDC authentication
🟡 PHASE 3 (RECOMMENDED): Multi-Repo Expansion
├─ Create deployment workflows
├─ Add separate deploy repo
├─ Reference shared actions from multiple repos
├─ Implement artifact sharing
└─ Timeline: 1-2 months
🔜 PHASE 4 (FUTURE): Multi-Team Setup
├─ Separate build/deploy/maintain repos
├─ Add monitoring & alerting
├─ Implement approval gates
├─ Team-level permissions
└─ Timeline: 3-6 months (when you have 10+ team members)
🔜 PHASE 5 (ENTERPRISE): Full Enterprise Setup
├─ Advanced security policies
├─ Cost optimization automation
├─ Comprehensive monitoring
├─ Disaster recovery procedures
└─ Timeline: As organization scales
Start Here:
│
├─ Do you have multiple repositories?
│ ├─ NO → Use COMPOSITE ACTIONS
│ │ ├─ Organizing jobs? → Add PARENT-CHILD WORKFLOWS
│ │ └─ Complex logic? → Add REUSABLE WORKFLOWS
│ │
│ └─ YES → How many teams/services?
│ ├─ 1-2 teams → REUSABLE WORKFLOWS
│ ├─ 3-5 teams → SHARED COMPOSITE ACTIONS ← YOU ARE HERE
│ │ Plan for Multi-Team next
│ ├─ 5-10 teams → SHARED COMPOSITE ACTIONS + MULTI-TEAM
│ └─ 10+ teams → FULL MULTI-TEAM SETUP
│
└─ Special Requirements?
├─ Need approval gates? → Multi-Team Setup
├─ Cost optimization? → Shared Actions + Cleanup
├─ High security? → Shared Actions + OIDC
└─ Disaster recovery? → Shared Actions + Backup
- acr-login - Login to Azure Container Registry
- build-docker-image - Build Docker image from Dockerfile
- push-docker-image - Push image to ACR
- backup-tag - Backup all current image tags
- cleanup-old-images - Remove old images, keep latest 10
All are documented in Shared-Composite-Actions.md
docker/
├── .github/
│ ├── actions/ (Local composite actions)
│ │ ├── acr-login/
│ │ ├── build-docker-image/
│ │ ├── push-docker-image/
│ │ ├── backup-tag/
│ │ └── cleanup-old-images/
│ └── workflows/
│ └── docker-build-deploy.yml
├── MCPAgent/ (Your Docker application)
│ ├── dockerfile
│ ├── mcp.py
│ └── requirements.txt
├── Shared-Composite-Actions/ (Shared actions repo structure)
├── Multi-Team-Setup/ (Multi-team setup guide)
├── Composite Actions/ (Learning materials)
├── Parent&Child/ (Learning materials)
├── Reusable/ (Learning materials)
├── PROJECT.md (Project details)
├── CONVERSATION_HISTORY.md (How this evolved)
└── README.md (This file)
✅ Complete Coverage: Each guide goes from basics to advanced
✅ Real Examples: All examples use your actual MCP Docker application
✅ Production Ready: All YAML code is tested and ready to use
✅ Troubleshooting: Each guide includes common issues and solutions
✅ Security: Security best practices included in every guide
✅ Performance: Optimization techniques for faster workflows
✅ Enterprise Patterns: Advanced patterns for large organizations
Every guide includes:
- Clear explanations for beginners
- Key concepts and terminology
- Simple examples to get started
- Folder structure and organization
- Step-by-step instructions
- Complete YAML code examples
- Real-world scenarios with MCP Agent
- Copy-paste ready configurations
- Complex patterns and strategies
- Error handling and debugging
- Performance optimization
- Security best practices
- Troubleshooting guides
- Common issues and solutions
- Monitoring and alerting
- Best practices
Start here in order:
- Composite-Actions-Setup.md - Basics
- Parent-and-Child-Workflows.md - Orchestration
- Reusable-Workflows.md - Multi-repo
Focus on these:
- Reusable-Workflows.md - Advanced patterns
- Shared-Composite-Actions.md - Centralized management
- Parent-and-Child-Workflows.md - Complex orchestration
Deep dive into:
- Security sections in all guides
- Advanced patterns in each guide
- Performance optimization sections
- Monitoring & rollback in Multi-Team-Setup
- Breaking changes management in Shared-Composite-Actions
Read:
- Multi-Team-Setup.md - Architecture
- Parent-and-Child-Workflows.md - Orchestration
- Shared-Composite-Actions.md - Reusable components
Read:
- Shared-Composite-Actions.md - Action management
- Reusable-Workflows.md - Workflow reuse
Read in order:
- Composite-Actions-Setup.md - Fundamentals
- Parent-and-Child-Workflows.md - Orchestration
- Reusable-Workflows.md - Advanced reuse
- Shared-Composite-Actions.md - Enterprise setup
- Multi-Team-Setup.md - Complete solution
- Choose a guide based on your experience level
- Read the basics section to understand concepts
- Implement using the step-by-step instructions
- Customize the YAML code for your needs
- Advanced dive into advanced patterns when ready
✅ Start with Composite-Actions-Setup.md if you're new
✅ Reference Shared-Composite-Actions.md for organization
✅ Use Multi-Team-Setup.md for scaling
✅ All files include real Docker/MCP examples
✅ All YAML code is production-ready
- PROJECT.md - Complete project documentation
- CONVERSATION_HISTORY.md - How this project evolved
Choose your learning path above and start reading the guides!