Security mirrors

One of GitLab’s core values is “public by default”, which means we develop in the open. One exception to this is security fixes, because developing security fixes in public discloses vulnerabilities before a fix is available, exposing ourselves and our users to attacks.

In order to work on these security issues in private, public GitLab projects have a security mirror in the gitlab-org/security group.

Below we’ll outline processes and considerations for creating these mirrors and keeping them in sync with their public (“Canonical”) counterparts.

Note: To create and configure a security mirror Owner access to the Security group is required, for compliance purposes this is limited to Delivery team members. If you’re outside the Delivery team and require a Security mirror to be set up file an issue on the Delivery tracker.

Creating a Security mirror

A Security mirror:

  • must be a fork of its Canonical project. Our release tooling relies on this fork relationship to verify the status of the mirroring configurations between all of a project’s repositories.
  • should have the same subgroup structure as its Canonical project, but within the security subgroup. For example, a project at gitlab-org/build/images/example should have a Security mirror at gitlab-org/security/build/images/example. This makes it easier to reason about where the Canonical project will be for a Security project, and vice-versa.
  • should give a clear indication to GitLab team members that it’s a Security project. Prior examples of this would be adding the lock icon (🔒) as a prefix in the project name field, and modifying the project description (e.g., 🔒 Security mirror of gitlab-org/gitlab 🔒).
  • should require each merge request to receive at least one approval from a member of the gitlab-com/gl-security/appsec group.
  • should disable project features it doesn’t need, such as the Container registry, Forks, Wikis, and Snippets.

Configuring mirroring

We rely on push mirroring from the Canonical project to update the Security project.

In the Canonical project:

  1. Go to Settings > Repository > Mirroring repositories
  2. Change Mirror direction to Push
  3. Fill in Git repository URL with the HTTPS URL to the Security repository, along with the gitlab-bot username (e.g., https://gitlab-bot@gitlab.com/gitlab-org/security/gitlab.git)
  4. In the 1Password Engineering vault, view the gitlab.com - gitlab-bot credentials.
  5. Copy the Merge Train and Security mirror token password into the Password field.
  6. Enable the Keep divergent refs and Only mirror protected branches options.

If the project also needs to be mirrored to Build (dev.gitlab.org) for its release process, follow these steps to set up the repo in Dev and create a new mirror in the Security project:

  1. Go to dev.gitlab.org/gitlab and click (top right) to create a New project
  2. Select Import project and set up using the Canonical repository url
  3. Add the gitlab_pushbot as a Maintainer on the project
  4. In the Security project go to Settings > Repository > Mirroring repositories
  5. Change Mirror direction to Push
  6. Fill in the Git repository URL with the HTTPS URL to the dev.gitlab.org repository, along with the gitlab_pushbot username (e.g., https://gitlab_pushbot@dev.gitlab.org/gitlab/gitlab-ee.git)
  7. In the 1Password Build vault, view the gitlab_pushbot credentials.
  8. Copy the Security to Build (dev) push mirroring password into the Password field.
  9. Enable the Keep divergent refs and Only mirror protected branches options.

NOTE:
If the project has its releases managed by release-tools, ensure that @gitlab-release-tools-bot has Maintainer level access to all the mirrors of the project. The recommended way to do this is to share the project with the Delivery team GitLab group in both GitLab.com and dev.gitlab.org. The Release Tools Bot is a member of this GitLab group and will automatically inherit the permissions.