This is the right first question, and it deserves an answer before I go any further.

cruft solves the snapshot problem by recording the template version a project was generated from and offering cruft update to apply later template diffs as a patch. It's a real improvement over cookiecutter generate, and for a single layer of inheritance (community template → service) it's simpler than what I'm about to describe. Where cruft starts to creak is at the second layer: when your organization wants to express opinions on top of the community template that every service then inherits. cruft doesn't model "fork of a fork" naturally, and patch-based updates are less forgiving than three-way merges when conflicts get gnarly. If you only need one layer of inheritance, use cruft and stop reading.

Internal packages (acme-fastapi-core, acme-observability) are the right answer for runtime concerns: middleware, auth wiring, observability hooks, database session helpers. Anything that can live behind a function call should live behind a function call. But packages don't ship project structure – they don't give you a Dockerfile, a CI pipeline, a directory layout, an Alembic config, deployment manifests, or the boilerplate that wires the packages together. Most mature platform teams end up doing both: a fork hierarchy for the scaffold, packages for the runtime behaviour. This post is about the scaffold half.

Monorepos sidestep the problem entirely by removing the boundaries that allowed drift in the first place. If you already have working monorepo tooling, you probably don't need this post. If you don't, adopting Bazel or Pants to solve a template-drift problem is a heavy detour.

With those out of the way: here's the fork story.

This is the open source template you've chosen as your foundation. You don't modify it directly. It represents the community's best understanding of how to build this type of service⁶.

A warning before going further: a fork chain is also a supply chain, and the same mechanism that propagates security fixes downstream propagates malicious or buggy commits with equal efficiency. Treat the choice of upstream like the choice of any other production dependency. Concretely, before adopting an upstream:

• Check that the project has more than one active maintainer, a recent release cadence, and evidence that someone reviews PRs. A scaffold maintained by one person on weekends is a single point of failure for your fleet.
• Pin to signed tags, not upstream/main. Require commit signature verification at the Tier 2 boundary so an upstream account compromise can't ride a git fetch straight into your services.
• Subscribe the org fork to the upstream's GitHub Security Advisories and OSV feeds. Many projects ship security fixes silently in point releases without filing a CVE.
• Run pip-audit / osv-scanner on every Tier 2 merge. An SBOM generated at this boundary is the only honest record of what you actually shipped to teams. An ORG_CHANGES.md manifest documents intent; an SBOM documents reality.

This is where your platform team applies organizational opinions on top of the community template. This fork is maintained by your platform or infrastructure team and represents your org's "blessed" way to build a service of this type.

Typical org-level customizations include:

• Authentication: Swap JWT for your org's OIDC provider or service mesh auth.
• Observability: Add your org's OpenTelemetry configuration, custom metrics, and tracing headers.
• Secrets management: Integrate with Vault, AWS Secrets Manager, or whatever your org uses.
• CI/CD: Replace generic GitHub Actions with your org's pipeline templates.
• Deployment manifests: Add Kubernetes manifests, Helm charts, or Terraform modules that match your infrastructure.
• Compliance: Add security scanning, license checking, and audit logging requirements.
• Internal libraries: Wire in your org's shared Python packages for common concerns.

The platform team's job is to keep this fork synchronized with upstream while maintaining the org's customizations⁷.

Individual teams fork the org's gold standard to create their specific services. A team building a payments service forks acme-corp/fastapi-service-template into acme-corp/payments-service, then adds their domain-specific models, routes, and business logic.

Teams get the org's opinions "for free" and can focus entirely on their domain problem. When the platform team pushes an improvement to the gold standard (say, upgrading the OpenTelemetry SDK or fixing a connection pool misconfiguration), teams can pull that change into their fork with a standard git merge.

On GitHub, fork the community template into your org's namespace:

tiangolo/full-stack-fastapi-template → acme-corp/fastapi-service-template

Then clone your org fork locally:

git clone git@github.com:acme-corp/fastapi-service-template.git
cd fastapi-service-template
git remote add upstream git@github.com:fastapi/full-stack-fastapi-template.git
# Disable accidental pushes to upstream
git remote set-url --push upstream no_push
git remote -v
# origin    git@github.com:acme-corp/fastapi-service-template.git (fetch)
# origin    git@github.com:acme-corp/fastapi-service-template.git (push)
# upstream  git@github.com:fastapi/full-stack-fastapi-template.git (fetch)
# upstream  no_push (push)

This is a critical decision⁸. I recommend maintaining two long-lived branches in the org fork:

• upstream-mirror: Tracks the upstream template exactly. Never commit org changes here.
• main: Contains the org's customizations on top of upstream.

# Create the mirror branch from upstream's main, NOT from your customized main
git fetch upstream
git checkout -b upstream-mirror upstream/main
git push origin upstream-mirror

# main branch is where org customizations live
git checkout main

When you want to sync with upstream:

# Update the mirror
git checkout upstream-mirror
git fetch upstream
git merge upstream/main
git push origin upstream-mirror

# Merge upstream changes into org's main
git checkout main
git merge upstream-mirror
# Resolve conflicts, keeping org customizations where intentional
git push origin main

The upstream-mirror ranch gives you a clean diff between "what upstream looks like" and "what our org version looks like." This is invaluable for understanding exactly what your org has changed.

For simple, infrequent syncs, GitHub's "Sync fork" button and the gh repo sync CLI command offer lighter-weight alternatives. These work well when the org fork has minimal divergence, but for forks with significant customizations you'll want the mirror-branch workflow above to keep a clear audit trail.

Now apply your org's opinions to main. The single most important rule: keep the diff between your fork and its upstream as small as possible. Every line you change in a file that upstream also changes is a future merge conflict. Before modifying an upstream file, ask: "Can I achieve this by adding a new file instead?" Often you can. A new org_middleware.py that's imported by the entrypoint is better than editing the middleware directly.

Some specific guidelines:

Prefer additive changes over modifications. Adding new files (a deploy/ directory, an internal_libs/ package, a .github/workflows/ci.yml) is low-conflict. Modifying files that upstream also modifies (main.py, requirements.txt, Dockerfile) is high-conflict.

Use configuration layers. Instead of editing settings.py directly, create an org_settings.py that imports and extends the base settings. This isolates your changes from upstream's evolution of the settings module.

Document every divergence. Maintain an ORG_CHANGES.md file that catalogs what you've changed and why. When merge conflicts arise, this document tells you whether the conflict is in code you intentionally modified. A typical manifest looks like:

## Org Customizations

### Authentication (modified: app/core/security.py)
- Replaced JWT auth with OIDC integration via org's identity provider
- Added service-to-service mTLS validation

### Observability (added: app/observability/)
- OpenTelemetry auto-instrumentation with custom span attributes
- Structured logging via [[https://www.structlog.org/en/stable/][structlog]] with org-standard fields

### CI/CD (replaced: .github/workflows/)
- Upstream GitHub Actions replaced with GitLab CI
- Added SAST scanning, container scanning, license compliance

### Database (modified: app/core/db.py)
- Connection pool max_size increased from 10 to 50
- Added read-replica routing for GET endpoints

This document is your merge conflict playbook. When upstream changes app/core/security.py and you get a conflict, you check the manifest: "We intentionally replaced this with OIDC. Ignore upstream's changes to the JWT implementation, but check if they've changed anything else in this file."

A note on mechanics: GitHub will not let you fork acme-corp/fastapi-service-template into another repo in the same org via the fork button – a given upstream can only have one fork per namespace. In practice, teams create a new empty repo (acme-corp/payments-service), then seed it from the org template using git clone --bare and git push --mirror, and finally add the org template as a long-lived remote. You lose GitHub's fork-network UI for the Tier 2 → Tier 3 hop, but the git-level inheritance relationship is identical.

# One-time seeding of a new service repo from the org template
git clone --bare git@github.com:acme-corp/fastapi-service-template.git
cd fastapi-service-template.git
git push --mirror git@github.com:acme-corp/payments-service.git
cd .. && rm -rf fastapi-service-template.git

# Then clone the new service repo and wire up the org-template remote
git clone git@github.com:acme-corp/payments-service.git
cd payments-service
git remote add org-template git@github.com:acme-corp/fastapi-service-template.git
git remote set-url --push org-template no_push

Teams should similarly maintain an org-template-mirror branch and merge into main:

git checkout -b org-template-mirror
git fetch org-template
git merge org-template/main
git push origin org-template-mirror

git checkout main
git merge org-template-mirror

With the hierarchy in place, improvements flow downstream through the fork chain. Here's what different types of changes look like in practice:

graph LR
    subgraph "Change Propagation"
        direction LR
        U[Community<br/>Template] -->|"1. Publishes<br/>security fix"| O[Org Fork]
        O -->|"2. Platform team<br/>validates + merges"| OP[Org Main ✅]
        OP -.->|"3. Teams pull<br/>from org-template"| S1[payments-service ✅]
        OP -.->|"3. Teams pull<br/>from org-template"| S2[inventory-service ✅]
    end

Renames are the most common source of painful merge conflicts. If upstream renames app/core/config.py to app/settings/config.py, and your org fork has modifications to the original app/core/config.py, Git may not detect this as a rename-with-modification⁹. Instead, you'll see the old file deleted and a new file created, with your org's changes silently lost.

Mitigation: When merging upstream changes that include renames, always diff the deleted file against the new file manually. Use git diff –find-renames with a low similarity threshold to help Git detect renames:

git merge -X find-renames=40 upstream-mirror

Upstream pins sqlalchemy==2.0.30 in their requirements.txt. Your org fork has pinned sqlalchemy==2.0.25 because 2.0.30 has a regression with your custom dialect. Three months later, upstream bumps to sqlalchemy==2.1.0 with breaking API changes.

The danger escalates with lock files (poetry.lock, requirements.txt with hashes). Lock file conflicts are virtually impossible to resolve by hand¹⁰.

Mitigation: don't try to "layer" lock files – pip and poetry resolvers don't compose two requirement files cleanly, and -r base.txt followed by overrides will silently produce unsatisfiable resolutions. Instead, pick one of two honest strategies:

1. Single resolved lock file owned by the org fork. The org fork edits pyproject.toml directly to express its constraints (upper bounds on critical libs, swapped-in internal packages) and re-runs the resolver after every upstream merge. Yes, this means pyproject.toml and the lock file are high-conflict zones, but it's the only approach that produces a coherent dependency graph.
2. Constraints file. Keep upstream's requirements.txt unmodified and ship a separate constraints.txt that pip install -c constraints.txt -r requirements.txt consumes. Constraints don't add dependencies, only bound them, so they don't fight the resolver.

Run pip-audit (or osv-scanner) on every upstream merge so security regressions surface in the Tier 2 PR, not in production.

The application entrypoint (main.py, app/__init__.py, or wherever the FastAPI app instance is created) is a high-conflict zone. Both upstream and your org fork need to modify this file – upstream to add framework features, your org to wire in custom middleware, startup hooks, and shutdown handlers.

If upstream refactors the startup sequence (e.g., moving from a module-level app = FastAPI() to a factory function create_app()), every downstream fork that has modified the entrypoint will face a complex merge.

Mitigation:

• Use a lifecycle hooks pattern. Define well-known hook functions (on_startup(), on_shutdown(), configure_middleware()) in separate files that the entrypoint imports. Upstream owns the entrypoint; your org owns the hook implementations.
• If upstream doesn't support this pattern, propose it upstream. This is a legitimate contribution that benefits everyone.

Alembic migrations have a linear dependency chain: each migration references the previous one's revision ID¹¹. If upstream adds migration abc123 and your org fork adds migration def456, both claim to be the "head." Alembic calls this a "multiple heads" situation and refuses to run until you create a merge migration. (This is the same Alembic we chose in the decision table above – a great tool, but one that demands careful coordination across fork tiers.)

At the team fork level, every team has domain-specific migrations that diverge from the org template's migrations, compounding the problem further.

Mitigation: this is the case where you should break the inheritance. Each service owns its own database, so migration history is fundamentally per-service and shouldn't be inherited at all. The org template should ship migration infrastructure (the alembic.ini, env.py, naming conventions, CI checks for multiple heads) but ship zero migration revision files. Treat the alembic/versions/ directory as team-owned from day one and add it to the merge-conflict-prevention checklist alongside CI files. If you genuinely have org-wide tables (a shared audit log, a tenancy table), publish them as a library the team imports, not as inherited migrations.

CI/CD pipelines tend to be heavily customized at every level of the hierarchy. Upstream has generic GitHub Actions. Your org replaces them with GitLab CI. Teams add service-specific test stages.

If upstream restructures their CI (renaming jobs, changing the workflow file layout), the merge into your org fork touches files you've completely replaced.

Mitigation:

• Place CI files in a separate, clearly-namespaced directory. If upstream uses .github/workflows/, put your org's CI in .ci/ or .gitlab/. This eliminates conflicts entirely because you're adding files, not modifying upstream's.
• Alternatively, .gitignore upstream's CI files in your org fork and maintain your own.

Dockerfile, docker-compose.yml, and Kubernetes manifests are modified at every tier. Upstream sets up a basic multi-stage build. Your org adds security scanning layers, internal registry references, and specific base images. Teams add service-specific build arguments and sidecar containers.

Mitigation:

• Use Docker Compose extends or override files: docker-compose.yml (upstream) + docker-compose.org.yml (org overrides) + docker-compose.team.yml (team overrides).
• For Dockerfiles, consider a base image strategy: the org publishes a base image with org-specific layers, and team Dockerfiles use FROM acme-corp/python-service-base:latest instead of modifying the upstream Dockerfile.

If upstream renames the top-level Python package (e.g., app → fastapi_app), every file in every downstream fork that imports from app breaks. This is a cascading failure across the entire hierarchy.

Mitigation:

• This is one case where talking to upstream matters. If you're building an org's infrastructure on top of a template, consider opening an issue or PR that establishes the top-level package name as a stable API.
• If you can't prevent it, maintain a thin compatibility shim (app/__init__.py that re-exports from fastapi_app) in the org fork to give teams time to migrate. Remove the shim after a transition period.

The longer you wait between upstream syncs, the harder they get. If you sync monthly, you're merging a month of upstream changes against a month of org changes. Conflicts that would have been trivial in isolation become tangled messes when batched.

The fix is cadence. Set a regular sync schedule – weekly or biweekly – and treat it like any other maintenance task. Automate the fetch and attempt the merge in CI. If it succeeds cleanly, auto-merge. If it conflicts, create a PR for human review. The key is detecting divergence early, even if you don't resolve it immediately.

graph LR
    subgraph "Sync Cadence"
        direction LR
        W1[Week 1<br/>3 upstream commits<br/>easy merge ✅] --> W2[Week 2<br/>5 upstream commits<br/>easy merge ✅]
        W2 --> W3[Week 3<br/>2 upstream commits<br/>1 conflict ⚠️]
        W3 --> W4[Week 4<br/>4 upstream commits<br/>easy merge ✅]
    end

Compare this to syncing quarterly, where you'd face 14 upstream commits in a single merge with compounding conflicts.

Drift looks like a social problem – teams fork the org template, build their service, never sync again, and six months later the fork is frozen at the version from the day they started¹². The service still runs, so nobody notices.

Frame it as a vulnerability management problem instead, because that's what it actually is. A stale Tier 3 fork is a service silently carrying every CVE that's been patched in the org template since the last sync. "47 commits behind" is a number that no engineer will act on; "missing 3 advisories from the last 60 days, including a high-severity auth bypass" is.

Solutions:

• Advisory-aware staleness detection: a CI job that doesn't just count missing commits but cross-references them against the org template's changelog and the upstream's GHSA / OSV feed. Surface security-relevant gaps independently from the general freshness number.
• Freshness SLO with escalation: set a policy ("no team fork more than N weeks behind stable", "zero open security-channel releases") and enforce it by opening a tracking issue with an owner – not a dashboard nobody reads, and not a CI warning that scrolls past.
• Sync sprints as a fallback for general-cohort drift, but never as the only mechanism for security drift.

A GitHub Action to automate staleness detection looks like this:

# .github/workflows/upstream-sync-check.yml
name: Check Upstream Sync
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am
  workflow_dispatch:

jobs:
  check-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Fetch upstream
        run: |
          git remote add upstream https://github.com/tiangolo/full-stack-fastapi-template.git
          git fetch upstream
      - name: Check divergence
        run: |
          BEHIND=$(git rev-list --count HEAD..upstream/main)
          if [ "$BEHIND" -gt 0 ]; then
            echo "::warning::Org fork is $BEHIND commits behind upstream"
          fi

Run the same pattern on team forks, checking against the org template.

Because the org fork is shared infrastructure for every team, a bad change – a poorly configured middleware, a broken migration, a dependency bump with a subtle regression – can propagate to every service that syncs.

Clear ownership and review processes are essential:

• Dedicated owners: The platform team owns the org fork. Changes require review from at least one platform engineer, with branch protection and signed commits enforced. Two-person review for anything touching auth, crypto, or session lifecycle.
• Change classification: Not every upstream change needs to be merged. Evaluate each upstream release for relevance and risk, and tag releases accordingly (security / patch / minor / major).
• Changelog: Maintain a changelog that translates upstream changes into org-relevant context. "Upstream upgraded SQLAlchemy to 2.1. This changes how async sessions are created. If you've customized session creation, see migration guide."
• Semantic commit prefixes: Prefix commits to distinguish org customizations from upstream merges (org: vs upstream:). When a merge conflict shows up, you immediately know whether the conflicting change is one you own or one you inherited.

Sometimes a team's service diverges so far from the template that merging org-template updates becomes more work than it's worth. The payments service has rewritten the entire database layer to use event sourcing. The notifications service has replaced FastAPI's routing with a custom message broker integration. At this point, the fork relationship is a liability, not an asset.

This is fine, and it should be a normal part of the lifecycle, not a stigmatised escape hatch. Not every service needs to stay on the fork. When a service has genuinely unique requirements that make it architecturally different from the template, detach it:

# Remove the org-template remote
git remote remove org-template

# Delete the mirror branch
git branch -D org-template-mirror

To make detachment a normal part of service lifecycle rather than a stigmatized escape hatch, define clear criteria:

• If merging org-template updates has required manual conflict resolution in more than 50% of the last 10 syncs, consider detaching.
• If the service has replaced more than 30% of the template's files with custom implementations, consider detaching.
• If the service's architecture has diverged from the template's assumptions (different database, different auth model, different deployment target), detach.

Explicitly detaching is better than maintaining a fiction of inheritance that creates merge conflicts without delivering value. The fork hierarchy should be opt-in, not mandatory.

The critical gap is the org fork's CI. Upstream tests the template in isolation; team forks test their service. Without strong tests at Tier 2, broken upstream merges silently propagate to every team. In addition to the obvious unit and integration tests, write contract tests that exercise the interfaces team forks depend on – startup hooks, middleware ordering, session lifecycle – so a refactor that quietly changes a hook contract fails in a Tier 2 PR rather than in a team's production deploy.

Instead of forks, put all services in a single repository with shared libraries for common patterns:

monorepo/
├── libs/
│   ├── fastapi-common/     # Shared middleware, auth, config
│   ├── db-common/          # SQLAlchemy setup, session management
│   └── observability/      # OpenTelemetry, logging
├── services/
│   ├── payments/
│   ├── inventory/
│   └── notifications/
└── templates/
    └── service-scaffold/   # Cookiecutter for new services

Pros: Atomic changes across services and libraries, no merge conflicts, single CI pipeline, easy refactoring.

Cons: Requires monorepo tooling (Bazel, Pants, Nx)¹³, CI complexity scales with repo size, teams lose autonomy over their release cycle, doesn't inherit from community templates.

Best for: Organizations with strong platform teams and existing monorepo infrastructure.

Tools like cruft (built on top of Cookiecutter) solve the "snapshot problem" by tracking which template version was used to generate a project and offering an update mechanism¹⁴:

# Generate project from template
cruft create https://github.com/acme-corp/fastapi-template

# Later, update to latest template version
cruft update

cruft update computes the diff between the template version you generated from and the current version, then applies that diff to your project.

Pros: No Git fork management, works with any Cookiecutter template, clear diffing between template versions.

Cons: Updates are one-way (no pushing changes back to the template), conflicts are handled at the file level (less granular than Git), doesn't compose into a multi-tier hierarchy as naturally.

Best for: Organizations that want template inheritance without the Git overhead.

Platforms like Backstage provide service scaffolding as a feature of a broader developer portal:

• Service catalog with templates
• One-click service creation from "golden path" templates
• Built-in CI/CD integration
• Plugin ecosystem for org-specific features

Pros: Higher-level abstraction, UI-driven, integrates service creation with service management, good for organizations with many non-expert users.

Cons: Heavy infrastructure (Backstage itself is a significant service to maintain)¹⁵, templates are still snapshots (no inheritance), vendor-specific if using a commercial platform.

Best for: Large organizations (500+ engineers) with dedicated platform teams.

Instead of inheriting an entire project template, publish your patterns as installable packages:

# In your service's requirements.txt
acme-fastapi-core==2.3.0    # Auth, middleware, config
acme-db-common==1.5.0        # SQLAlchemy setup, migrations base
acme-observability==3.1.0    # OpenTelemetry, structured logging

Teams install these packages and compose their service from them:

from acme_fastapi_core import create_app, configure_auth
from acme_db_common import get_async_session, Base
from acme_observability import setup_tracing

app = create_app()
configure_auth(app)
setup_tracing(app)

Pros: Versioned dependencies with semantic versioning, teams can pin to specific versions, no merge conflicts, standard package management.

Cons: Requires extracting patterns into well-designed APIs (significant upfront investment), doesn't provide project structure (only runtime patterns), teams still need a scaffold for the "rest" of the project.

Best for: Organizations with mature platform teams that can invest in library design.

The fork hierarchy occupies a sweet spot: low upfront investment, inherits from community work, and scales to a meaningful number of services before the merge overhead becomes a bottleneck. For most mid-sized engineering organizations (50-500 engineers, 5-50 services on a common stack), it's the right starting point¹⁶.

These approaches aren't mutually exclusive. Mature organizations often combine package-based composition for runtime patterns (auth, observability, database utilities) with a fork hierarchy for project structure (directory layout, CI pipelines, deployment manifests, Dockerfile conventions). The fork gives you the scaffold; the packages give you the runtime behavior.