Connect GitLab

Connect GitLab when you want the Platform to access GitLab repositories and hook Identify, Protect, and Monitor into GitLab CI.

Choose how the organization authenticates to GitLab

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. The Platform does not store an organization-wide Maintainer token.
• 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.

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

After you choose a method

• OAuth organizations — Users who are not yet signed into GitLab 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 anyone can configure projects.
• Update existing projects — If the 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 with the same progress page as Watch a GitLab configuration job.

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 a 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.

Watch a GitLab configuration job

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 the job finishes, use the links on that page to open each project's integration merge request (when one was created), 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. 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.

Unconfigure a GitLab project

When you remove a repository from the enabled set on Settings → Integrations → GitLab, the Platform disables that project and cleans up the GitLab side of the integration:

• Removes the RunSafe webhook and Gremlin CI/CD variables for the project.
• Closes open RunSafe remediation merge requests for that project. Source branches are left in place.
• For organizations that use OAuth, revokes the Developer project access token the Platform minted for that project. Organization-wide Maintainer API tokens are not revoked.

If GitLab rejects a close or revoke call, the Platform still disables the project and clears stored project tokens. Reconfigure the repository later if you need Identify, Protect, or Monitor again.

Merge the 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.
• Adds Docker and .NET job wrappers when those build types are detected.
• Adds finalize discussion threads for C/C++, Docker, and .NET.

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

When using a centralized CI template (GitLab CI templates or GitHub workflows) for all of your projects, you can disable automatic MR creation under organization Settings → Integrations.

Wrap C and C++ compile jobs

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

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

- !reference [.runsafe-gremlin, setup_script]

2. Add this 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 Identify — C/C++ SBOM quickstart for background on build-time SBOMs.

Wrap Docker image builds

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

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]
    - ./my_custom_build_script.sh
    - !reference [.runsafe-gremlin, cleanup_script_docker]

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

Wrap .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.

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]
    - ./custom_software_build.sh
    - !reference [.runsafe-gremlin, cleanup_script_dotnet]

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

Commit Comments

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.

Compliance Setting

The .post Gremlin job runs compliance checks. The pipeline fails when license or vulnerability policy is violated. See Fail builds on vulnerability thresholds and Set license 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 Last Detected 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.
• Cannot configure projects — An organization admin must finish Maintainer authentication.

If this page does not resolve the issue, email support@runsafesecurity.com.

Related tasks

• Connect SCM
• Build with Jenkins
• Generate compiled SBOMs