How ipdxco/unified-github-workflows works
Project type and purpose
• This is a DevOps orchestration project (Unified CI) that lives in a single GitHub repo and automates:
• Rendering and distributing workflow templates
• Opening and merging PRs in participating repos
• Versioning and releasing its own code
• It leverages custom composite Actions, shell scripts, and GitHub’s REST/GraphQL APIs.
File structure
• Top-level areas:
• .github/actions/: composite Action definitions (inspect-releaser, read-config, read-go-mod, render-templates, etc.)
• .github/workflows/: reusable workflow definitions (copy-templates, create-prs, merge-prs, sync-forks, release workflows, tagpush, etc.)
• templates/: YAML templates shipped into target repos
• scripts/: Bash scripts invoked by workflows and Actions
• defaults.yml: the default config driving template rendering
• version.json, CHANGELOG.md, LICENSE: versioning and metadata
• Key patterns:
• Composite actions for modular steps
• Reusable workflows invoked from target repos
• Scheduled and event-driven pipelines
README insights
• Describes two main domains:
1. Template distribution pipelines (copy, create-PR, merge-PR, sync forks)
2. Versioning pipelines (release-check, releaser, tagpush)
• Emphasizes config layering: defaults.yml + per-repo .github/uci.yml or job-specific JSON files.
Main components & interactions
a. Components
1. Unified CI Repository
• Stores Templates, Defaults, Scripts, Actions, Workflows
2. GitHub Actions Runner
• Executes workflows on schedule or triggers
3. Custom Composite Actions
• E.g., render-templates: merges defaults, templates, repo config → final workflows
4. Shell Scripts
• Utility scripts (copy-templates.sh, update-go.sh, etc.)
5. GitHub API
• Used by create-prs, merge-prs, tagpush workflows
6. Participating Repositories
• Receive rendered workflows via PRs
b. Interactions
• Schedule trigger fires copy-templates.yml
→ Runner loads defaults.yml + optional .github/uci.yml from each target repo
→ render-templates action + scripts produce concrete workflow YAMLs
→ copy-templates commits changes into target repos via PR (GitHub API)
• Create-PR opens PRs for updated workflows
• Merge-PR auto-merges when checks pass
• Sync-forks keeps forks in sync if using organization-specific forks
• Release pipelines manage Unified CI’s own version.json:
– release-check.yml posts draft release and diagnostics
– releaser.yml publishes GH Release on merge
– tagpush.yml validates any manual tag pushes
c. Architectural patterns
• Event-driven pipelines: scheduled, push, PR events
• Template rendering: uses composite actions to abstract common logic
• Configuration layering: defaults → repo override → job override
• Reusable workflows: DRY, centrally maintained
d. Key technologies
• GitHub Actions (YAML workflows, composite actions)
• Bash scripting
• GitHub REST/GraphQL API
• YAML templating (workflow templates + defaults.yml)
Don’t overthink—capture all essential pieces
• Configuration sources separately (default vs per-repo vs job-specific)
• How reusable workflows in .github/workflows/ are referenced by templates