Skip to content

ADR-0001: Hybrid branching strategy — trunk IT, GitFlow OT

Status

Accepted — 2026-03-31

Context

The platform spans two fundamentally different workload types.

IT infrastructure — Ansible playbooks, Terraform configs, Kubernetes manifests, Docker compose files. These are idempotent, reversible, and can be redeployed quickly. Fast iteration is valuable. Long-lived feature branches create drift.

OT firmware and configs — ESP32 firmware, Node-RED flows, MQTT configs, Grafana dashboards tied to physical sensors. A bad deploy to caneast-c1-ot1-esp1 means a sump pit sensor goes offline. A bad firmware flash cannot be rolled back by a pipeline. Physical consequences exist.

A single branching strategy cannot serve both workloads appropriately.

Decision

IT repos (archon-platform, archon-cloud, archon-pipelines): trunk-based development. - All changes via short-lived feature/* branches → main - PRs required, squash merge only - Branch lifetime target: under 24 hours

OT folders in archon-apps: GitFlow. - feature/* → develop → release/* → main - develop is the staging gate for OT changes - release/* branches require manual approval before merge to main - Hotfixes via hotfix/* → main + backmerge to develop

IT/OT separation is enforced at the pipeline level — pipelines detect which paths changed and route accordingly.

Alternatives Considered

Full GitFlow everywhere — Too slow for IT infrastructure. A hotfix to an Ansible role should not require a release branch.

Full trunk-based everywhere — Insufficient change control for OT. No staging gate before physical system changes.

Separate repos per environment — Creates duplication, complicates cross-environment promotion, no clear benefit over folder-level separation.

Consequences

  • Two branching strategies must be understood and maintained
  • Pipeline logic must detect IT vs OT path changes separately
  • Branch policies in ADO must be configured per repo and per path
  • Stronger interview story: risk-appropriate governance, not one-size-fits-all

References

  • archon-apps develop branch policy (ADO)
  • Azure DevOps path filters on pipeline triggers