File Distribution Workflow¶
Automated file distribution across multiple repositories using GitHub Actions and GitHub Apps.
Pattern Overview
A three-stage workflow that discovers targets, distributes files in parallel, and reports results. Idempotent design ensures safe reruns.
Problem¶
Maintaining consistent files (documentation, configuration, policies) across many repositories requires:
- Manual updates to each repository
- Tracking which repos need updates
- Creating PRs and waiting for reviews
- Ensuring nothing gets missed
Solution¶
An automated distribution workflow that:
- Monitors changes to source files in a central repository
- Automatically distributes updates to target repositories
- Creates or updates pull requests in each target
- Provides visibility through workflow summaries
Patterns Applied¶
This workflow implements patterns from the Developer Guide:
| Pattern | Purpose |
|---|---|
| Three-Stage Design | Separates discovery, execution, and reporting |
| Matrix Distribution | Parallelizes operations with conditional logic |
| Idempotency | Ensures safe reruns after partial failures |
| Work Avoidance | Skips version-only changes |
Implementation Guide¶
Core Workflow¶
- Architecture - Three-stage workflow overview
- Stage 1: Discovery - Query organization for target repositories
- Stage 2: Distribution - Parallel distribution to each repository
- Stage 3: Summary - Aggregate and display results
Configuration¶
- Workflow Configuration - Triggers and permissions
- Supporting Scripts - Branch preparation and helper scripts
Reliability¶
- Idempotency - Safe re-execution guarantees
- Error Handling - Failure strategies and reporting
- Troubleshooting - Common issues and solutions
Extensions¶
- Extension Patterns - Multi-file, conditional, and template distribution
Operations¶
- Performance - Parallel processing and rate limits
- Monitoring - Workflow summaries and metrics
- Security - Token scope and audit trails
Best Practices¶
- Start Small - Test with 2-3 repositories before full rollout
- Monitor First Run - Watch logs carefully on initial deployment
- Gradual Rollout - Increase
max-parallelgradually - Clear Documentation - Document what files are distributed and why
- Review Process - Ensure PRs are reviewed before merging
Prerequisites¶
- GitHub App Setup - Organization-level GitHub App
- Actions Integration - Token generation in workflows