GitLab integration

This page covers connecting GitLab to the RunSafe Platform and finishing GitLab CI setup. It does not cover signing into the Platform itself with GitLab OAuth (account login).

Public CI templates live in ci-templates. Prefer this page for Platform behavior; use that repository for exact YAML includes and revision pins.

Organization Maintainer authentication

Before anyone can select repositories, an organization admin must choose how the organization provides GitLab Maintainer access on Settings → Integrations → GitLab:

• OAuth — Each user who configures projects connects with their own GitLab Maintainer account. No organization-wide Maintainer token is stored.
• API Token — Submit a GitLab group, project, or personal access token with the api and write_repository scopes and at least the Maintainer role. Optionally set the GitLab Instance URL for self-hosted GitLab. That token is stored once and used for the whole organization whenever RunSafe needs to access GitLab.

Non-admins see a warning until an organization admin completes this setup step.

After setup

• OAuth organizations — Users who are not yet signed into GitLab for the organization use Connect with OAuth. When signed in, the project tree shows Signed into GitLab as … with a disconnect control that ends only that user's OAuth session.
• API Token organizations — Users share the stored Maintainer credential and can browse the project tree without a separate OAuth step.
• Reconfigure (organization admins only) — Clears the organization's Maintainer token or OAuth setup choice. An organization admin must complete the initial setup step again before projects can be configured.
• Update existing projects — If the organization authentication method changes while projects are already configured, the Platform blocks further configuration until an organization admin runs Update existing projects. That starts a background job (same progress page as project configuration jobs) so existing projects use the new method.

GitLab.com Free groups (OAuth)

When the organization uses OAuth, configuring a project creates a GitLab Developer project access token. On GitLab.com, those tokens require a paid namespace (Premium or higher). Groups that do not support that appear locked in the project tree with the message that they require features that only work on paid versions of GitLab. Self-managed GitLab and organizations that use a shared API Token do not apply that lock the same way, because they do not mint those project tokens for configuration.

Configuring projects

Configuring GitLab repositories runs as a background job so large selections can finish without blocking the browser:

1. On Settings → Integrations → GitLab, select repositories (or groups) and the features to enable, then start configuration.
2. The Platform opens a GitLab project configuration page that shows live progress, including which projects succeeded or failed.
3. When configuration finishes, use links on that page to open each project's integration merge request (when one was created), return to configure more projects, or go to Projects.

If a project fails with a retryable error, use Retry, Retry remaining, or Retry configuration on the job page to start a new job for those projects. License-limit failures also offer retry after you free capacity or upgrade.

Only one GitLab configuration job can run for an organization at a time. If another job is already active, the Platform points you to that job instead of starting a second one.

Settings → Integrations also lists recent configuration jobs under Recent integrations so you can reopen an in-progress or completed job.

Integration merge request

When you enable Identify, Protect, and/or Monitor for a GitLab project, RunSafe opens a merge request that adds the Gremlin CI template (.pre setup, .post artifact collection and compliance, and shared job references).

The MR:

• Includes rs-gremlin.gitlab-ci.yml (or equivalent) with RunSafe Gremlin Setup in the .pre stage and RunSafe Gremlin Artifact Collection in the .post stage.
• Replaces vulnerable base images and dependencies when RunSafe auto-remediation applies.
• Adds Docker and .NET job wrappers when those build types are detected.
• Adds finalize discussion threads for C/C++, Docker, and .NET (see below).

Merge the MR into the default branch, then run a pipeline and confirm progress on Project → Settings → Integrations (setup checklist and Last contact).

You can disable automatic MR creation under organization Settings → Integrations if your organization uses a centralized CI template instead.

If integration changes are later removed from the pipeline, reintroduce them by reconfiguring the project or following the manual job steps below.

C and C++ builds

C/C++ compile jobs always need a manual step after the integration MR is merged. The MR includes a Finalize RunSafe C/C++ Integration discussion with this guidance. The Platform cannot reliably infer every compile job.

For each GitLab CI job that compiles C or C++:

1. Add the following to before_script or the start of script:

- !reference [.runsafe-gremlin, setup_script]

2. Add the following to after_script or the end of script:

- !reference [.runsafe-gremlin, cleanup_script]

Example with both in script:

build_job:
  script:
    - !reference [.runsafe-gremlin, setup_script]
    - make
    - !reference [.runsafe-gremlin, cleanup_script]

3. If the job uses needs, add the RunSafe setup job to the dependency list (cloud: RunSafe Gremlin Setup; on-prem: RunSafe Gremlin Setup On-prem):

build_job:
  needs:
    - job1
    - job2
    - RunSafe Gremlin Setup

4. Commit and run a new pipeline on the default branch.

See also Identify — C/C++ SBOM quickstart for background on build-time SBOMs.

Docker image builds

The integration MR wraps detected Docker jobs automatically. If a job runs docker / podman commands but was not wrapped (or SBOMs are missing), wrap that job manually. The MR includes a Finalize RunSafe Docker SBOM Integration discussion with the same guidance.

Before docker commands:

- !reference [.runsafe-gremlin, setup_script_docker]

After docker commands:

- !reference [.runsafe-gremlin, cleanup_script_docker]

Example:

build_job:
  script:
    - !reference [.runsafe-gremlin, setup_script_docker]
    - docker build -t example-tag .
    - !reference [.runsafe-gremlin, cleanup_script_docker]

Apply the same needs addendum as for C/C++ if the job lists needs.

.NET builds

The integration MR wraps detected .NET jobs automatically when the Platform finds .csproj, .fsproj, .vbproj, .sln, packages.config, or global.json. If a job runs dotnet commands but was not wrapped, add the steps below. The MR includes a Finalize RunSafe .NET SBOM Integration discussion with the same guidance.

Before the first dotnet command:

- !reference [.runsafe-gremlin, setup_script_dotnet]

After the last relevant dotnet command:

- !reference [.runsafe-gremlin, cleanup_script_dotnet]

Example:

build_job:
  script:
    - !reference [.runsafe-gremlin, setup_script_dotnet]
    - dotnet build
    - !reference [.runsafe-gremlin, cleanup_script_dotnet]

Include the RunSafe setup job in needs when the job uses needs.

Commit comments and compliance

When Identify finishes SBOM work for a GitLab pipeline commit, the Platform posts a commit comment with links to the project-scoped SBOM reports for that git ref. If too many SBOMs were generated to list, the overflow link opens that project's SBOM list for the same ref.

The .post Gremlin job runs compliance checks. The pipeline fails when license or vulnerability policy is violated (see Vulnerability compliance and License compliance policy).

Troubleshooting

• Last contact never updates — Confirm the MR is merged, Gremlin jobs ran on the default branch, and the project has Identify and/or Protect enabled. Last contact means the Platform heard from GitLab CI; see Detection vs last contact.
• Wrong or missing CI under Continuous integration — After editing .gitlab-ci.yml (or other CI files) on the default branch, use Refresh CI detection on Project → Settings → Integrations. Detection is one-shot unless you refresh; see Detection vs last contact.
• Cannot configure projects — An organization admin must finish Maintainer authentication.

If this page does not resolve the issue, email [email protected].

Related documentation

• Integrations overview
• Projects and source control
• Identify — compiled SBOMs