Document build infrastructure separation requirements

---

title: "Build Infrastructure"

---

GitLab's release artifact build pipeline uses mirrored repositories, each with a distinct role.

The current state of which services build where is documented here and updated as services migrate.

For the decision rationale behind this architecture, see [ADR 001: Build Mirror Separation](decisions/001_build_mirror_separation.md).

## Repository Mirrors

| Mirror | Location | Purpose |

|--------|----------|---------|

| Canonical | GitLab.com | Public development, merge request workflows, canonical source of truth |

| Security | GitLab.com | Private mirror for pre-disclosure security fixes; source for building and publishing release artifacts for new modular services |

| Build | dev.gitlab.org | Private mirror for building and publishing release artifacts for legacy processes |

## New components: Security mirror

New modular services build and publish release artifacts from the Security mirror on GitLab.com.

GitLab CI runners execute on compute that is separate from GitLab.com application servers.

This dedicated runner fleet, combined with the Security mirror's restricted access model, satisfies the logical separation between build infrastructure and production environments required by SOC 2, FedRAMP, and SLSA L2+.

The Security mirror's activity is independently auditable and its access is scoped separately from the Canonical project's maintainer pool.

## Existing processes: dev.gitlab.org

Legacy tooling and processes continue to run builds through [dev.gitlab.org](https://dev.gitlab.org), a separate GitLab instance.

As the build system evolves - particularly as GitLab moves toward a more modular release architecture - these processes will naturally migrate away from the separate instance.

This is a gradual transition rather than a discrete migration effort.

For operational details on dev.gitlab.org and the build machines, see the [Build team maintenance documentation](build/maintenance/).

As part of the team tasks, team has responsibility towards the following nodes/tasks:

* `dev.gitlab.org`: This internal GitLab instance runs nightly CE packages and

  is used for building official packages as well as hosting security release

  related MRs before publishing. Details of the node as well as the maintenance

  tasks can be found in [the dev.gitlab.org specific docs](dev-gitlab-org/).

  is used for building official packages. See [Build Infrastructure](../../build-infrastructure.md)

  for context on how this instance fits into the broader build pipeline.

  Details of the node as well as the maintenance tasks can be found in

  [the dev.gitlab.org specific docs](dev-gitlab-org/).

* Build Machines: Runner manager machines that spins up machines that are used

  by various CI jobs for building and publishing packages. Details of the node

---

title: "Delivery ADR 001: New components use security mirror, not dev.gitlab.org"

owning-stage: "~group::release-and-deploy"

toc_hide: true

---

## Context

GitLab historically built and published release artifacts from a dedicated, separate GitLab instance

([dev.gitlab.org](https://dev.gitlab.org)). This provided a control plane boundary distinct from

GitLab.com and a fallback in the event of a GitLab.com outage.

As GitLab moves toward a more modular release architecture, the question arose whether new services

must continue using this separate instance or could instead use the security mirror on GitLab.com.

The full discussion is recorded in

[gitlab-com/gl-infra/delivery#21976](https://gitlab.com/gitlab-com/gl-infra/delivery/-/work_items/21976).

The core compliance question was: do SOC 2, FedRAMP, SLSA, and related frameworks require a separate

GitLab instance for builds, or do they require logical separation between build infrastructure and

production environments?

After consultation with Security and Compliance ([@madlake](https://gitlab.com/madlake),

[@jhebden](https://gitlab.com/jhebden)):

- No compliance framework mandates a separate GitLab instance. The requirement is **logical separation**

  between where software is built and where it runs in production.

- GitLab CI runners execute on compute infrastructure that is separate from GitLab.com application

  servers. This dedicated runner fleet constitutes the "build infrastructure" for compliance purposes.

- The Security mirror operates with its own restricted access model, separately auditable from the

  Canonical project. Builds triggered from it are scoped to that context.

- This combination, dedicated runners outside the production environment triggered from the

  access-controlled Security mirror, satisfies SOC 2 (CC8.1, CC6.1, CC6.6), FedRAMP, and SLSA L2+

  logical separation requirements.

## Decision

**New modular services and components do not need to use dev.gitlab.org.** They build and publish

release artifacts from the Security mirror on GitLab.com, using the dedicated CI runner fleet.

Existing processes that use dev.gitlab.org continue unchanged and are migrated gradually as the

broader release architecture evolves. This decision does not affect them.

## Consequences

- New components have a simpler, lower-maintenance build path. Repository mirroring to dev.gitlab.org

  is not required for new services.

- Logical separation between build infrastructure and production is maintained and auditable.

- Existing dev.gitlab.org tooling and processes are unaffected; migration is gradual and not required

  for compliance.

- The "chicken-and-egg" availability concern (GitLab.com outage blocking GitLab builds) remains a

  consideration for existing processes on dev.gitlab.org. For new modular components, this risk is

  acceptable by their service teams.  Should later this be deemed inappropriate, we may continue creating a third mirror as we do today.

- This reduces scope for which we need to audit with less instances in scope for monitoring.

## Workflow

1. Stable branches are created when the initial release candidate of a monthly release is tagged.

1. After creation, stable branches are automatically propagated to [security](https://gitlab.com/gitlab-org/security) and [dev](https://dev.gitlab.org/) repositories via repository mirroring.

1. After creation, stable branches are automatically propagated to [security](https://gitlab.com/gitlab-org/security) and [dev](https://dev.gitlab.org/) repositories through repository mirroring.

1. Bug and security fixes are [backported](/handbook/engineering/releases/backports) to stable branches based on the [maintenance policy](https://docs.gitlab.com/policy/maintenance/).

1. Changes backported to stable branches are automatically deployed to [release environments](https://gitlab.com/gitlab-com/gl-infra/release-environments) to guarantee they're compatible with the GitLab version.

1. Patch and internal releases are created from the content of stable branches.

- Stable branch permissions are based on the [maintenance policy](https://docs.gitlab.com/policy/maintenance/). Stable branches associated with

the [maintained versions](https://docs.gitlab.com/policy/maintenance/#maintained-versions) are opened to GitLab maintainers for merging while older stable branches are limited to Release Managers.

- To account for security fixes and [release environments](https://gitlab.com/gitlab-com/gl-infra/release-environments), security repositories represent the SSOT for stable branches.

- Tests on stable branches are the same on canonical, security and dev repositories. With the exception

of release environments that are only available on the GitLab security repository.

- Tests on stable branches are the same on canonical and security repositories, with the exception of release environments that are only available on the GitLab security repository.

## Build Infrastructure

Release artifacts are built from mirrored repositories using dedicated CI runner infrastructure.

For a full description of which mirrors exist, what builds where, and the rationale behind this architecture, see the

[Build Infrastructure documentation](../infrastructure-platforms/gitlab-delivery/build-infrastructure.md).

## Broken Stable Branches