Skip to content

Commit a689539

Browse files
StevenTCramerStevenTCramer
committed
Deploy sync workflow: Sync workflow documentation
🤖 Deployed by TimeWarp Flow orchestrator
1 parent 528e08e commit a689539

1 file changed

Lines changed: 218 additions & 0 deletions

File tree

‎.github/workflows/sync-configurable-files.md‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
# Sync Configurable Files Workflow
2+
3+
This workflow automatically synchronizes configurable files from multiple repositories to child repositories, ensuring consistency across multiple projects. It features an enhanced repos-based configuration system with advanced path transformation capabilities.
4+
5+
## Overview
6+
7+
The sync workflow runs on a scheduled basis (default: every Monday at 9:00 AM UTC) and can also be triggered manually. It downloads specified files from configured repositories with intelligent path mapping and creates pull requests in child repositories when updates are detected.
8+
9+
## Files
10+
11+
- `sync-configurable-files.yml` - The main GitHub Actions workflow
12+
- `sync-config.yml` - Configuration file defining which files to sync
13+
- `SYNC_WORKFLOW.md` - This documentation file
14+
15+
## Configuration
16+
17+
### Enhanced Repos-Based Configuration
18+
19+
The workflow uses an enhanced configuration system via `.github/sync-config.yml` that supports:
20+
21+
- **Multiple repositories**: Sync from different repositories with specific configurations
22+
- **Path transformations**: Automatic prefix removal and path mapping
23+
- **Default behaviors**: Intelligent destination path defaults
24+
- **Repository-specific settings**: Branch and transformation rules per repository
25+
- **Schedule management**: Cron expression for automated runs
26+
- **Pull request settings**: Configuration for generated PRs
27+
28+
Example enhanced configuration:
29+
```yaml
30+
# Global defaults
31+
default_repo: 'TimeWarpEngineering/timewarp-architecture'
32+
default_branch: 'master'
33+
34+
# Sync schedule
35+
schedule:
36+
cron: '0 9 * * 1' # Every Monday at 9:00 AM UTC
37+
38+
# Repository-specific configurations
39+
repos:
40+
- repo: 'TimeWarpEngineering/timewarp-architecture'
41+
branch: 'master'
42+
path_transform:
43+
remove_prefix: 'TimeWarp.Architecture/' # Auto-remove prefix from dest paths
44+
files:
45+
# When dest_path is omitted, defaults to source_path with prefix removal
46+
- source_path: 'TimeWarp.Architecture/.gitignore'
47+
- source_path: 'TimeWarp.Architecture/.editorconfig'
48+
- source_path: 'TimeWarp.Architecture/.github/workflow-templates/'
49+
50+
# Explicit destination override
51+
- source_path: 'TimeWarp.Architecture/templates/custom.md'
52+
dest_path: 'docs/custom-template.md'
53+
54+
# Global sync options
55+
sync_options:
56+
default_dest_to_source: true # Auto-default dest_path to source_path
57+
overwrite_existing: true
58+
ignore_missing: false
59+
60+
# Files to exclude globally
61+
exclude_files:
62+
- '.github/sync-config.yml'
63+
```
64+
65+
### Manual Trigger Options
66+
67+
The workflow can be manually triggered with custom parameters:
68+
69+
- **parent_repo**: Override the parent repository
70+
- **parent_branch**: Override the parent branch
71+
- **files_to_sync**: Comma-separated list of files (overrides config file)
72+
- **use_config_file**: Whether to use the configuration file (default: true)
73+
74+
## How It Works
75+
76+
1. **Enhanced Configuration Loading**: Loads repos-based settings from `sync-config.yml`
77+
2. **Path Processing**: Applies path transformations and defaults destination paths
78+
3. **Multi-Repository Download**: Downloads files from configured repositories with parallel processing
79+
4. **Intelligent Path Mapping**: Maps source paths to destination paths with prefix removal
80+
5. **File Comparison**: Compares downloaded files with current repository files using hash comparison
81+
6. **PR Creation**: Creates a pull request with detailed changes if differences are found
82+
7. **Comprehensive Summary**: Provides detailed summary including file specifications and transformations
83+
84+
## Supported File Types
85+
86+
The workflow can sync any type of file, including:
87+
88+
- Configuration files (`.gitignore`, `.editorconfig`, etc.)
89+
- Workflow templates
90+
- Build configuration files
91+
- Documentation templates
92+
- Code quality configurations
93+
94+
## Security Considerations
95+
96+
- Uses `GITHUB_TOKEN` or `SYNC_PAT` for authentication
97+
- Only syncs explicitly configured files through repos-based structure
98+
- Creates PRs for review rather than direct commits
99+
- Supports `SYNC_PAT` for workflows requiring special permissions
100+
- Automatically excludes workflow files when `SYNC_PAT` is not available
101+
- Path transformations are controlled and validated
102+
103+
## Troubleshooting
104+
105+
### Common Issues
106+
107+
1. **Permission Denied**: Ensure the repository has proper permissions for the GitHub Actions bot
108+
2. **File Not Found**: Check that files exist in the configured repositories at the specified branches
109+
3. **PR Creation Failed**: Verify that the repository allows PR creation from GitHub Actions
110+
4. **Configuration Parse Error**: Verify the repos-based configuration structure is correct
111+
5. **Path Transform Issues**: Check that prefix removal settings match actual source paths
112+
113+
### Debugging
114+
115+
1. Check the workflow run logs for detailed error messages and file specifications
116+
2. Verify the repos-based configuration file syntax with a YAML validator
117+
3. Test path transformations manually to ensure they work as expected
118+
4. Use manual trigger to test specific repository and file combinations
119+
5. Review source repository permissions and branch access
120+
6. Check if `SYNC_PAT` is needed for workflow files
121+
122+
## Best Practices
123+
124+
1. **Start Small**: Begin with a few critical files before expanding the configuration
125+
2. **Review PRs**: Always review generated PRs before merging to verify transformations
126+
3. **Test Configuration**: Use manual triggers to test repos-based configuration changes
127+
4. **Use Path Transformations**: Leverage `remove_prefix` to clean up destination paths
128+
5. **Default Behavior**: Rely on `default_dest_to_source` for simplified configuration
129+
6. **Regular Maintenance**: Periodically review and update the repos-based sync configuration
130+
7. **Security**: Keep sensitive files out of the sync configuration and use `SYNC_PAT` when needed
131+
132+
## Customization
133+
134+
### Changing the Schedule
135+
136+
Modify the cron expression in either the workflow file or configuration:
137+
138+
```yaml
139+
schedule:
140+
cron: "0 9 * * 1" # Every Monday at 9 AM UTC
141+
```
142+
143+
### Adding Custom Logic
144+
145+
The workflow can be extended with additional steps for:
146+
147+
- Custom file processing
148+
- Conditional synchronization
149+
- Integration with other tools
150+
- Notification systems
151+
152+
### Branch Protection
153+
154+
Consider setting up branch protection rules to:
155+
156+
- Require PR reviews
157+
- Run status checks
158+
- Enable auto-merge for trusted updates
159+
160+
## Enhanced Configuration Examples
161+
162+
### Sync Development Configuration with Path Transformation
163+
164+
```yaml
165+
repos:
166+
- repo: 'TimeWarpEngineering/timewarp-architecture'
167+
branch: 'master'
168+
path_transform:
169+
remove_prefix: 'TimeWarp.Architecture/'
170+
files:
171+
- source_path: 'TimeWarp.Architecture/.gitignore'
172+
- source_path: 'TimeWarp.Architecture/.editorconfig'
173+
- source_path: 'TimeWarp.Architecture/.eslintrc.js'
174+
- source_path: 'TimeWarp.Architecture/.prettierrc.json'
175+
```
176+
177+
### Multi-Repository Configuration
178+
179+
```yaml
180+
repos:
181+
- repo: 'TimeWarpEngineering/timewarp-architecture'
182+
branch: 'master'
183+
path_transform:
184+
remove_prefix: 'TimeWarp.Architecture/'
185+
files:
186+
- source_path: 'TimeWarp.Architecture/Directory.Build.targets'
187+
- source_path: 'TimeWarp.Architecture/NuGet.config'
188+
189+
- repo: 'TimeWarpEngineering/templates'
190+
branch: 'main'
191+
files:
192+
- source_path: 'workflows/ci.yml'
193+
dest_path: '.github/workflows/ci-template.yml'
194+
- source_path: 'docs/README.template.md'
195+
```
196+
197+
### Complex Path Mapping Example
198+
199+
```yaml
200+
sync_options:
201+
default_dest_to_source: true
202+
203+
repos:
204+
- repo: 'TimeWarpEngineering/timewarp-architecture'
205+
branch: 'master'
206+
path_transform:
207+
remove_prefix: 'TimeWarp.Architecture/'
208+
files:
209+
# Will become: .templates/ (prefix removed)
210+
- source_path: 'TimeWarp.Architecture/.templates/'
211+
212+
# Explicit override ignores prefix removal
213+
- source_path: 'TimeWarp.Architecture/docs/CONTRIBUTING.md'
214+
dest_path: 'CONTRIBUTING.md'
215+
216+
# Default behavior: source becomes dest with prefix removed
217+
- source_path: 'TimeWarp.Architecture/tools/build.ps1' # → tools/build.ps1
218+
```

0 commit comments

Comments
 (0)