Template Management
Syncing upstream changes from the template repository.
Tip
First time? Read Setup and Standard Workflow.
Quick Reference is your copy-paste guide.
Common Patterns and Troubleshooting are optional deep-dives.
Philosophy
This template uses transparent git-based syncing rather than opaque automation. You control what updates to pull and when, with full visibility into changes.
Why git sync?
- Transparent: Review changes before applying
- Selective: Pull only what you need
- Flexible: Resolve conflicts your way
- No magic: Standard git commands, no proprietary tools
Setup
One-time configuration:
# Add template repository as foundation remote
git remote add foundation https://github.com/your-org/agent-foundation.git
git remote -v # Verify
# Fetch foundation tags to refs/foundation-tags/* (avoids conflicts with local tags)
# --no-tags prevents git from also creating local copies in refs/tags/*
# See: https://git-scm.com/book/en/v2/Git-Internals-The-Refspec
git fetch foundation 'refs/tags/*:refs/foundation-tags/*' --no-tags
Verify foundation tags were fetched:
# List foundation tags with dates
git for-each-ref refs/foundation-tags --format='%(refname:short) | %(creatordate:short)' --sort=-creatordate
Note
git tag -l only lists refs in refs/tags/*, not custom namespaces. We need git for-each-ref for refs/foundation-tags/*
Standard Workflow
Prepare
Check for updates
git fetch foundation 'refs/tags/*:refs/foundation-tags/*' --no-tags
git for-each-ref refs/foundation-tags --format='%(refname:short)' --sort=-version:refname | head -10 # Semantic version sort (latest first)
Choose version and set variable
# Set version for copy-paste workflow (e.g., v0.9.1)
VERSION=v0.9.1
# Review what changed
git show foundation-tags/$VERSION:CHANGELOG.md
git log --oneline foundation-tags/v0.9.0..foundation-tags/$VERSION
Create sync branch
Sync
Sync files in stages (see Common Patterns for detailed examples)
# Compare foundation vs current HEAD
git diff --stat foundation-tags/$VERSION -- . ':!src/' ':!tests/'
# Stage foundation files - review with git status, edit staged files before commit
git checkout foundation-tags/$VERSION -- docs/
git commit -m "docs: sync with $VERSION"
git checkout foundation-tags/$VERSION -- .github/workflows/
git commit -m "ci: sync workflows from $VERSION"
git checkout foundation-tags/$VERSION -- terraform/
git commit -m "infra: sync terraform from $VERSION"
Resolve conflicts if needed
git status
git mergetool
git add <resolved-files>
git commit --amend # Amend most recent sync commit with resolved conflicts
Restore custom files if needed
Review
Add manual changes for heavily customized files
git diff foundation-tags/$VERSION -- README.md
# Manually edit README.md to incorporate improvements
git add README.md
git commit -m "docs: incorporate upstream README improvements from $VERSION"
Verify sync (customize ignore patterns for expected diffs)
Test & Merge
Test thoroughly
uv run ruff format && uv run ruff check --fix && uv run mypy
uv run pytest --cov
docker compose up --build
terraform -chdir=terraform/bootstrap/dev plan
Create PR and merge
git push -u origin sync/foundation-$VERSION
gh pr create --title "Sync with foundation template $VERSION"
# Review and merge via GitHub
Tip
Advanced: To sync unreleased changes from foundation/main, fetch the branch (git fetch foundation main) and replace foundation-tags/$VERSION with foundation/main in commands above.
Quick Reference
Sync strategy by file type. Complete Setup and Prepare to create a branch and set a version (e.g., VERSION=v0.9.1)
Safe to sync (review staged changes for project customizations):
Note
terraform/ may contain project-specific resource configurations. docs/ may contain custom guides and environment variables. Always review staged changes before committing.
git checkout foundation-tags/$VERSION -- .github/workflows/
git checkout foundation-tags/$VERSION -- terraform/
git checkout foundation-tags/$VERSION -- docs/ mkdocs.yml
git checkout foundation-tags/$VERSION -- notebooks/
git checkout foundation-tags/$VERSION -- .gitignore .dockerignore
# Review: git status && git diff --cached
Review and edit manually (project-specific):
# Review diffs, manually edit files to incorporate changes
git diff foundation-tags/$VERSION -- README.md AGENTS.md
git diff foundation-tags/$VERSION -- Dockerfile docker-compose.yml .env.example
git diff foundation-tags/$VERSION -- pyproject.toml
Review upstream patterns (apply manually):
Foundation may enhance reusable code patterns. Review diffs and selectively apply improvements:
# Review utils patterns (Pydantic validation, OpenTelemetry)
git diff foundation-tags/$VERSION -- src/agent_foundation/utils/
# Review test patterns (pytest fixtures, ADK mocks)
git diff foundation-tags/$VERSION -- tests/conftest.py
Never sync (your code):
- src/ - Your agent implementation
- tests/ - Your test suite
- CHANGELOG.md - Your version history
- init_template.py - Removed from your project after first use
- LICENSE - Your project license
- uv.lock - Regenerate with uv lock after syncing pyproject.toml
Warning
After syncing pyproject.toml, run uv lock to regenerate lockfile. Never sync uv.lock - CI uses uv sync --locked which fails on stale lockfile.
Common Patterns
Detailed examples for the Standard Workflow Sync and Review phases.
Pull Entire Directory
Warning
Stages all files from foundation version. Overwrites local versions of tracked files in this directory. Untracked local files are not affected. Review with git status before committing.
# Review changes (compares foundation vs current HEAD)
git diff foundation-tags/$VERSION -- docs/
# Sync directory
git checkout foundation-tags/$VERSION -- docs/
git commit -m "docs: sync with foundation $VERSION"
Pull Specific File
# Review changes
git diff foundation-tags/$VERSION -- docs/deployment.md
# Sync file
git checkout foundation-tags/$VERSION -- docs/deployment.md
git commit -m "docs: sync deployment.md from $VERSION"
Sync a File at a Different Local Path
git checkout requires the same path in both the source and destination. When the foundation uses a different package directory name (e.g., agent_foundation/ vs. your_agent/), use git show to redirect the content instead:
# Review the diff across different paths
git diff foundation-tags/$VERSION:src/agent_foundation/utils/observability.py -- src/your_agent/utils/observability.py
# Write the foundation version to your local path
git show foundation-tags/$VERSION:src/agent_foundation/utils/observability.py > src/your_agent/utils/observability.py
git commit -m "chore: sync observability.py from foundation $VERSION"
Pull Multiple Related Files
# Sync workflows
git checkout foundation-tags/$VERSION -- .github/workflows/
git commit -m "ci: sync workflows from $VERSION"
# Sync Terraform
git checkout foundation-tags/$VERSION -- terraform/bootstrap/
git commit -m "infra: sync bootstrap from $VERSION"
Cherry-Pick Specific Commits
# View commits between versions (adjust range as needed)
git log --oneline foundation-tags/v0.9.0..foundation-tags/$VERSION
# Cherry-pick specific commit
git cherry-pick <commit-sha>
# Or: create patch and review
git format-patch -1 <commit-sha>
git apply --check 0001-*.patch # Test first
git apply 0001-*.patch # Apply if clean
git commit -m "feat: cherry-pick improvement from $VERSION"
Resolve Conflicts
# Attempt sync
git checkout foundation-tags/$VERSION -- docs/deployment.md
# If conflicts occur
git status # Shows conflicted files
# Resolve manually (look for <<<< ==== >>>>) or use merge tool
git mergetool
# After resolving
git add docs/deployment.md
git commit -m "docs: merge deployment.md from $VERSION"
Restore Custom Files
If you accidentally overwrite custom files:
# Sync directory
git checkout foundation-tags/$VERSION -- docs/
git commit -m "docs: sync with $VERSION"
# Restore custom file from previous commit
git checkout HEAD~1 -- docs/custom-tools.md
git commit --amend
Add Manual Changes
For heavily customized files (README, AGENTS.md), manually incorporate improvements:
# View upstream changes
git diff foundation-tags/$VERSION -- README.md
git show foundation-tags/$VERSION:README.md # Or view full file
# Manually edit your file to incorporate useful changes, then commit
git add README.md
git commit -m "docs: incorporate upstream README improvements from $VERSION"
Troubleshooting
# Check for accidental local tag conflicts
git show-ref | grep -E 'refs/tags/(v[0-9])'
# Delete specific local foundation tags (safe - only affects local refs)
git tag -d v0.9.0 v0.9.1
Caution
The following commands delete ALL local tags. Verify remote state before proceeding.
# Reset all local tags to origin
git ls-remote --tags origin # Verify what you'll restore
git tag -d $(git tag -l) # Delete all local tags
git fetch origin --tags # Restore from remote
# Reset foundation-tags namespace (safe - only affects local refs)
git for-each-ref refs/foundation-tags --format='%(refname)' | xargs -n 1 git update-ref -d
git fetch foundation 'refs/tags/*:refs/foundation-tags/*' --no-tags