Skip to content

Overview

Principles

The system is a GitHub template. A fork created from it gets guided initialization, controlled upstream integration, and ongoing maintenance, all built from GitHub-native workflows, issues, rulesets, releases, and packages.

  • Self Configuring

    An initialization issue captures the upstream repository, creates the branch topology, deploys fork workflows, and applies repository settings.

  • Safety First

    Each branch stage validates before promoting, backed by rulesets and security scanning.

  • Event Driven

    Scheduled, pull-request, push, issue-comment, and manual events drive synchronization, validation, release, and recovery.

  • Scalable

    Every fork runs the same workflows, so adding a service repository adds no new patterns.

System Design

The template repository pattern separates template development from fork operation:

graph TD
    A[Template Repository] --> B[Fork Instance 1]
    A --> C[Fork Instance 2]
    A --> D[Fork Instance N]

    B --> E[Upstream OSDU library]
    C --> F[Upstream OSDU legal]
    D --> G[Upstream OSDU storage]

    style A fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    style B fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style C fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style D fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px

Template Development Context is .github/workflows/: the template's own CI, initialization, documentation build, and the tests for the update propagation mechanism.

Fork Instance Context receives the files from .github/template-workflows/ as deployed .github/workflows/, plus fork-owned configuration, actions, and build assets.

Event Driven Architecture means the workflows respond to GitHub events: scheduled events (daily sync), change events (PR validation), and manual dispatch (on-demand sync or cascade).

Two components carry most of the design:

  • Three-Branch Strategy

    Isolated conflict resolution and controlled integration from upstream through staging to production environments.

    Learn about branch strategy

Source and Artifact Ownership

The engineering system separates ownership rather than mirroring every upstream file:

  • The sync workflow regenerates fork_upstream from the upstream tip, retaining shared code while removing provider implementations and upstream deployment assets.
  • Azure provider and test source is seeded once, then owned on main and fork_integration.
  • Validation builds core,azure by default; provider-less fork_upstream builds core only.
  • The engineering system supplies build/Dockerfile, which packages the Azure JAR built from source.
  • Trusted validation events publish multi-architecture images to public GHCR; release automation adds the semantic-version tag without rebuilding.

See ADR-033, ADR-035, ADR-037, and ADR-038.

Enterprise Capabilities

The system combines repository rulesets, CodeQL, Dependabot validation, trusted-event package publication, and GitHub App authentication. The default-branch ruleset keeps human approval on main, the integration-branch ruleset lets automation maintain fork_upstream and fork_integration, and the Copilot code review ruleset requests a Copilot review on every main pull request where the organization supports it. Forks receive centrally maintained workflows and the shared Dockerfile while keeping ownership of their Azure source and filter configuration. A pull request to main that changes a file present on fork_upstream fails Check Paths unless it carries the port label declaring a deliberate port (ADR-038).