| name | tgc-sync-provider |
| description | Synchronize a downstream Terraform provider repository with Magic Modules by aligning commit history and verifying parity. |
tgc-sync-provider
Note to AI Agents: You MUST read the YAML frontmatter above first. Only read the rest of this file if the description matches your required task.
This skill is designed to be completely self-contained and unambiguous for a fresh agent without prior context.
Prerequisites
- You must be operating relative to the
magic-modules and downstream provider repositories.
- You must have the absolute path to the downstream repository.
- You must have verified there are no unsaved or uncommitted changes in the downstream provider directory that would be overwritten by code generation.
How to Choose Your Path
Before proceeding, determine which synchronization method you need:
- Aligning to a Specific Base Commit: Use this if you need to synchronize the repositories to a specific state in the past (e.g., to match a specific pull request or isolate a failure). Follow the numbered Execution Steps below.
- Synchronizing to Latest (Fast-Forward): Use this if you simply want to bring both repositories up to date with their latest remote commits. Follow the steps in the Synchronizing to Latest section.
- Skip Synchronization: Use this if you want to bypass synchronization to save time. Follow the steps in the Skip Synchronization section.
Execution Steps
1. Identify Magic Modules Base Commit
Check if the magic-modules repository is a fork or has multiple remotes:
git remote -v
Identify the official googleapis/magic-modules remote (e.g., origin or upstream).
If it is ambiguous, ask the user which remote is the canonical upstream.
Then calculate the target base commit:
Record the base commit hash and date. This hash will be used to find the matching commit in the downstream repository.
2. Check for Uncommitted Downstream Changes
Before checking out older commits, check if there are local modifications in the downstream repository:
cd <downstream-provider-path>
git status
If changes exist, always clean the uncommitted and untracked files in the downstream repository using git reset --hard and git clean -fd.
3. Find the Matching Downstream Commit
Search for a commit in the downstream repository that corresponds to the Magic Modules base commit hash:
cd <downstream-provider-path>
git log -n 50 --grep="[upstream:<MM-hash>]"
If not found, search origin/main (in case your local main is behind):
git log -n 50 --grep="[upstream:<MM-hash>]" origin/main
If found, pull your main or checkout the specific commit. If not found, try history traversal before falling back to date-based matching.
Fallback: History Traversal (Recommended)
If the exact base hash is not found, it is likely because the specific magic-modules commit did not generate code changes for this specific provider (resulting in no downstream generation commit).
Walk backwards through the magic-modules commit history from your base commit. For each parent commit:
- View previous commit history:
git log -n 10 --format="%H %s"
- Search for its hash in the downstream:
git log --grep="[upstream:<parent-hash>]"
- The first commit found is the true synchronization point where the downstream repository diverges or sits.
Fallback: Date-Based Matching
If no commit message contains the hash, find the commit in the downstream repository that is closest to the date/timestamp of the MM base commit:
git log --since="<date-of-base-minus-2-days>" --until="<date-of-base-plus-2-days>"
Select the commit that appears to be the matching nightly or generation commit. If ambiguous, ask the user for clarification.
4. Align Downstream
Checkout the matching commit in the downstream repository:
git checkout <matching-commit-hash>
5. Verify Parity
Return to magic-modules and run the automation script from tgc-build-skill to generate code and verify parity:
./.agents/skills/tgc/tgc-build-skill/scripts/build_tgc.sh <downstream-provider-path>
Verify the output of git status in the downstream repository. It should be clean or only contain changes from our specific branch.
6. Verification & Handoff
Verify that the make tgc command succeeded without unexpected diffs. Return to the workflow that invoked this skill to proceed.
Synchronizing to Latest (Fast-Forward)
If your goal is to bring both repositories to their most recent remote commits rather than aligning to an older base:
1. Update Magic Modules to Latest
Fetch the latest changes from the canonical remote (e.g., upstream or origin) and rebase your feature branch on it. This avoids failures if main is already checked out in another worktree:
git fetch <canonical-remote> main
git rebase <canonical-remote>/main
2. Clean and Update Downstream to Latest
Downstream is generated, so clean local changes first to avoid conflicts. Then fetch the latest commit from the remote main branch:
cd <downstream-provider-path>
git reset --hard
git clean -fd
git fetch origin main
3. Project Latest Changes
Return to magic-modules and run the build script to project all changes to the latest downstream state:
./.agents/skills/tgc/tgc-build-skill/scripts/build_tgc.sh <downstream-provider-path>
Skip Synchronization
If you are confident that the downstream repository and Magic Modules are already synchronized, or you explicitly wish to bypass this phase:
1. Confirm Parity
Briefly check the status of both repositories to ensure there are no uncommitted or conflicting changes:
git status
cd <downstream-provider-path>
git status
2. Proceed to the Next Phase
Skip all checkout/sync steps and directly proceed to the next phase of the workflow.
