The Internal Developer Platform

Infrastream is not just an infrastructure provisioning engine — it is a complete Internal Developer Platform (IDP) that manages the full lifecycle of your software, from the first git push to a running service in production. This section provides a thorough explanation of how the platform automates source code management, CI/CD, versioning, and deployment.

---

1. Branching Strategies

Infrastream automatically provisions and enforces a branching strategy for every repository. You choose a strategy in the GithubRepository manifest, and the platform configures branch protection rules, merge policies, CI triggers, and versioning behavior accordingly.

Available Strategies

GitHub Flow (GITHUB_FLOW)

The simplest model. All development happens in short-lived feature branches that merge directly into main.

Branch	Purpose	Merge Policy	Version Type
main	Primary release branch	Squash only	LATEST — full semver (v2.4.13)
feat/*, fix/*, docs/*, etc.	Feature/bugfix branches	Any	NONE — no tag

Best for: Small teams, microservices with continuous deployment, projects that don't need a staging branch.

Branch protection:

• main requires 1 reviewer, status checks must pass (the Merge Authorized gate), and only conventional-commit-prefixed branches (feat/, fix/, docs/, test/, ci/, refactor/, perf/, chore/, revert/) can merge into it.
• Feature branches have no reviewer requirement and accept any merge method.

---

Git Flow (GIT_FLOW)

A structured model with main, develop, release, hotfix, and feature branches. Designed for products with a formal release cycle.

Branch	Purpose	Merge Policy	Version Type
main	Production-ready code	Merge only (from release/hotfix)	LATEST — full semver
develop	Integration branch	Squash from feature branches	ALPHA — pre-release (v2.4.13-alpha.3)
release/*/*	Stabilization branches	Merge/squash (bugfixes only)	BETA — pre-release (v2.4.13-beta.2)
hotfix/*	Emergency production fixes	Any	HOTFIX — hotfix tag (v2.4.13-hotfix.1)
feat/*, fix/*, etc.	Feature branches	Any	NONE — no tag

Best for: Enterprise products, mobile apps with App Store release cycles, products with long QA phases.

Key rules:

• Only release/* and hotfix/* branches can merge into main.
• Only conventional-commit branches, release branches, and hotfix branches can merge into develop.
• Release branches only accept bugfix/ and fix/ branches.

---

Trunk-Based Development (TRUNK_BASED)

All development merges directly into main (the "trunk"). When a release is cut, a long-lived release branch is created that snapshots a specific tag. These release branches allow post-release maintenance — bugfixes, security patches, and minor improvements — without disrupting trunk development. This makes Trunk-Based a middleground between GitHub Flow and Git Flow: it has the simplicity of a single trunk for active development, but retains the ability to maintain older releases independently.

Branch	Purpose	Merge Policy	Version Type
main	Trunk (single source of truth)	Squash only	LATEST — full semver
release/*/*	Long-lived release maintenance branches (snapshot a tag)	Merge/squash (bugfixes only)	HOTFIX — hotfix tag
feat/*, fix/*, etc.	Feature branches	Any	NONE — no tag

Best for: High-velocity teams, platform infrastructure, libraries that need to maintain multiple release lines.

---

How Strategies Are Configured

You don't write branch protection rules manually. The strategy field on the GithubRepository manifest controls everything:

apiVersion: lowops.manifests.v1
kind: GithubRepository
metadata:
  name: my-service
  github-connection: pvotal-tech
  # ...parent metadata
spec:
  strategy: GITHUB_FLOW    # or GIT_FLOW, TRUNK_BASED
  permissions:
    administrators:
      groups: [platform-team]
    contributors:
      groups: [backend-engineers]

The engine computes the full branch configuration during the Compute phase and provisions:

• GitHub Rulesets — branch protection rules with merge restrictions, required reviewers, and status checks
• CI Workflows — per-branch push and pull request workflows (see next section)
• CODEOWNERS — auto-generated from the permissions and codeOwners fields

Conventional Commits

All strategies enforce Conventional Commits (feat:, fix:, docs:, etc.) on both PR titles and commit messages. On pull requests, the platform automatically derives the appropriate release/major, release/minor, or release/patch label from the PR title. On push, it validates every commit message against the conventional commit format.

---

2. Automatic CI Provisioning

Every repository in Infrastream gets a complete CI pipeline without writing a single line of workflow YAML. You define a BuildDefinition manifest, and the engine generates the full GitHub Actions configuration.

The BuildDefinition Manifest

A BuildDefinition describes what your project is (Go, Flutter, Java, etc.) and what stages it should go through (analysis, test, build, containerize, etc.).

apiVersion: lowops.manifests.v1
kind: BuildDefinition
metadata:
  name: my-service
  # ...parent metadata (must be a child of GithubRepository)
spec:
  type: GOLANG
  stages:
    - analysis
    - security-scan
    - test
    - build
    - containerize
  golang:
    versions: ["stable"]
    buildType: bin
    target: ./cmd/server
  containerize:
    - name: my-service
      registries: [core-registry]

What Gets Generated

For each branch in the branching strategy, the engine generates two workflow files:

1. Caller workflow — Lives in the repository. A lightweight file that delegates to the managed workflow via workflow_call.
2. Managed workflow — Lives in a shared managed-workflows-private repository. Contains the actual build logic, hardened with SHA-pinned action references.

my-service/
  .github/workflows/
    my-service-primary-branch-push.yml        ← caller
    my-service-primary-branch-pull_request.yml ← caller

managed-workflows-private/
  .github/workflows/
    my-service-my-service-primary-branch-push.yml        ← managed
    my-service-my-service-primary-branch-pull_request.yml ← managed

Why Two Repositories?

The split architecture provides security isolation. The managed workflow runs with elevated permissions (Workload Identity, Artifact Registry push) that are never exposed in the application repository. Developers see only the lightweight caller workflow and cannot modify the CI pipeline.

Supported Build Types

Type	Stages Available	Package Registries
GOLANG	analysis, security-scan, test, build, release, containerize	Docker (Artifact Registry)
DOCKER	containerize	Docker
FLUTTER	analysis, test, publish	Dart (custom registry)
FLUTTER_WEB	analysis, test, build, containerize	Docker
JAVA	analysis, security-scan, test, build, publish, containerize	Maven (Artifact Registry)
PYTHON	analysis, test, build, publish, containerize	PyPI (Artifact Registry)
PROTOBUF	analysis, test, publish	Buf Schema Registry
HELM	analysis, test, publish	Helm (OCI Registry)
TERRAFORM	validate, plan, publish	Terraform Registry
MOJO	test, build, publish	Custom

CI Pipeline Stages

Each push or pull request workflow is composed of the following stages (in order):

Pull request workflows run only the analysis, security-scan, test, and build stages — they never tag, containerize, or deploy.

Push workflows run the full pipeline, culminating in the PubSub notification that triggers the CD system.

AI-Powered CI Components

For private repositories with spec.aiAssistant.pullRequest.enabled: true, the engine additionally generates:

• AI Code Review — Automated code review on every pull request using Gemini
• AI Documentation — Automatic documentation generation on merge (Markdown, Confluence, or Notion)
• AI PR Helper — PR enrichment, labeling, and summarization

Analytics Integration

When configured, CI pipelines automatically upload test and security scan results to BigQuery for long-term analytics:

• Test reports — CTRF-formatted results with pass/fail/skip/flaky counts, durations, and per-test details
• Security reports — SARIF-formatted vulnerability scans with severity levels and affected packages

---

3. Automatic Versioning

Infrastream computes version numbers automatically. You never manually bump a version or create a git tag.

How Version Computation Works

The Initialize Pipeline stage of every push workflow runs a compute-version script that:

1. Inspects PR labels — Finds the merged PR that produced the push commit and reads its release labels
2. Determines bump level:
   • release/major label → major bump
   • release/minor label → minor bump
   • No label (default) → patch bump
3. Finds the base tag — The latest non-pre-release semver tag reachable from HEAD
4. Computes the target version — Based on the release type configured for the branch:

Release Type	Base Tag	Bump	Result
LATEST (main)	v2.4.12	minor	v2.5.0
LATEST (main)	v2.4.12	patch	v2.4.13
ALPHA (develop)	v2.4.12	—	v2.4.12-alpha.3
BETA (release/*)	v2.4.12	—	v2.4.12-beta.0
HOTFIX (hotfix/*)	v2.4.12	—	v2.4.12-hotfix.1
NONE (feature/*)	—	—	No tag, pipeline skipped

Label Derivation from PR Titles

On pull requests, the platform automatically derives release labels from the PR title using Conventional Commits:

PR Title	Breaking?	Derived Label
feat(auth): add OAuth2 support	No	release/minor
fix(api): correct status code	No	(none — default patch)
feat(db)!: redesign schema	Yes (!)	release/major
refactor: clean up imports	No	(none — default patch)

Idempotency

If the commit is already tagged, the pipeline sets skip=true and all downstream jobs are bypassed. This prevents double-tagging when a push is replayed.

---

4. Continuous Deployment

The CD system orchestrates how built artifacts move through environments to reach production. It is managed by two distinct tracks: PreRelease and Release.

The ReleaseTrack Manifest

A ReleaseTrack defines the pipeline stages for deployment:

apiVersion: lowops.manifests.v1
kind: ReleaseTrack
metadata:
  name: my-product-releasetrack
spec:
  preReleaseStages:
    - environments:
        - development
  releaseStages:
    - environments:
        - staging
    - environments:
        - production
  hotfixStages:
    - environments:
        - staging
    - environments:
        - production

PreRelease Deployments

PreRelease deployments are triggered automatically when a CI build completes and publishes a PubSub notification.

Key characteristics:

• Per-application — Only the single service that was built is deployed
• Automatic — No human intervention required for pre-release environments
• Fast feedback — Developers see their changes running within minutes
• Version is a semver tag — e.g., v2.4.13, written directly to spec.version in the DeploymentConfig manifest

Release Deployments

Release deployments are triggered manually by a Release Manager through the Infrastream Portal.

Key characteristics:

• Bundled — All applications in the ApplicationSet are released together as a single atomic unit
• Version-locked — The RC tag points to a specific image digest. Every environment in the pipeline deploys the exact same binary
• Manual approval — Promotions between stages require stakeholder sign-off (see Approval Gates below)
• Immutable tags — RC tags (rc.0, rc.1) are never moved. Each promotion attempt creates a new RC increment, providing a complete audit trail

Approval Gates & Stakeholder Roles

The ReleaseTrack manifest defines the path for a release, but the Infrastream Portal enforces stakeholder approvals at each stage. Different stakeholders own different stages:

Stage	Stakeholders	Responsibility	Mechanism
PreRelease (development)	Development Team	Code correctness & quality	Automated — CI deploys on merge, integration tests run automatically
Release (staging)	QA / Test Engineers	Validate bundled release stability	Manual sign-off in Portal before promotion
Release (production)	Product Managers, Security Team	Business approval & compliance	Mandatory multi-party sign-off in Portal
Hotfix (staging → production)	SRE / Operations, Senior Leadership	Incident resolution	Accelerated approval — smaller designated group of incident commanders

Separation of Concerns

The release lifecycle separates three roles:

• Development Teams own the Application manifest — they define what gets deployed
• Product / Release Managers own the ApplicationSet — they decide which applications ship together
• Platform / SRE Team owns the ReleaseTrack — they define how and where it deploys

This ensures autonomy at each level while maintaining governance.

Release Candidate (RC) Tagging

When a Release is initiated, the system tags each application's container image in Artifact Registry before writing the version to any manifest. This ensures that when the Engine reconciles a DeploymentConfig, the referenced image always exists.

The RC tag is derived from the ApplicationSet name and the bundle version:

infrastream-cloud-2026.11-rc.0
└── appSet ──────┘ └── bundle ┘ └── increment

Hotfix Deployments

Hotfixes follow an accelerated path via the hotfixStages. They bypass the full release track to get critical fixes to production fast:

1. A developer creates a hotfix/* branch from the release branch
2. The CI pipeline tags it as a HOTFIX version (v2.4.13-hotfix.1)
3. The CD system deploys it through the hotfix stages (typically staging → production)

Pipeline Completion & Production Tagging

When a Release reaches the final stage successfully:

1. Clean tag — A production tag is created by stripping the -rc.N suffix (e.g., infrastream-cloud-2026.11)
2. Hotfix tag — If the clean tag already exists (because of a hotfix), a hotfix variant is created (e.g., infrastream-cloud-2026.11-hotfix.1)
3. All tags are immutable and provide a complete audit trail

Version Naming Convention

Tag Type	Format	Example	Created By
Semver	v<major>.<minor>.<patch>	v2.4.13	CI pipeline (push to main)
Alpha	v<major>.<minor>.<patch>-alpha.<N>	v2.4.13-alpha.3	CI pipeline (push to develop)
Beta	v<major>.<minor>.<patch>-beta.<N>	v2.4.13-beta.2	CI pipeline (push to release/*)
Hotfix	v<major>.<minor>.<patch>-hotfix.<N>	v2.4.13-hotfix.1	CI pipeline (push to hotfix/*)
Release Candidate	<appSet>-<bundle>-rc.<N>	infrastream-cloud-2026.11-rc.0	CD Manager (release initiation)
Production	<appSet>-<bundle>	infrastream-cloud-2026.11	CD Manager (pipeline completion)

---

5. Supply Chain Security

The CI/CD pipeline includes built-in supply chain security:

Binary Authorization

Every container image published through the pipeline receives a Binary Authorization attestation signed with a KMS key. The target GCP projects are configured to only run containers with a valid attestation, preventing unauthorized images from being deployed.

Workflow Hardening

All generated managed workflows are hardened — action references use SHA-pinned versions instead of mutable tags (e.g., actions/checkout@abc123 instead of actions/checkout@v4). This prevents supply chain attacks via compromised actions.

Workload Identity Federation

CI workflows authenticate to GCP using Workload Identity Federation (OIDC tokens) — no service account keys are stored in GitHub. The pipeline authenticates, builds, pushes, and deploys entirely via short-lived federated credentials.

Token Broker

For private repositories that need cross-repo access (e.g., pulling shared libraries), a Token Broker service provides short-lived GitHub tokens without exposing any long-lived secrets.