Skip to main content

GitLab Integration

GitGuardian Scout (ggscout) can be configured to collect secrets and CI/CD variables from GitLab instances, enabling you to inventory and monitor secrets stored in your GitLab environment.

Overview​

The GitLab integration allows ggscout to:

  • Collect CI/CD variables from GitLab projects, groups, and the instance
  • Inventory secrets stored in GitLab CI/CD variable settings

Prerequisites​

Before configuring the GitLab integration, ensure you have:

  1. GitLab instance access (GitLab.com or self-hosted GitLab)
  2. Personal Access Token or Project/Group Access Token with appropriate permissions
  3. GitGuardian API token with NHI permissions
  4. ggscout deployed in your environment (Docker, Kubernetes, or local installation)

Configuration​

1. GitLab Access Token​

Create a GitLab access token with the read_api scope.

GitLab only returns CI/CD variables to a token with a high enough role. ggscout skips any project or group where the token's role is too low, so a token with a low role produces an inventory that looks complete but is mostly empty.

Variables collectedRole GitLab requires
Project variablesMaintainer or Owner on the project
Group variablesOwner on the group
Instance variablesAdministrator (GitLab self-managed only)

With an administrator's token, ggscout collects the variables of every project and group of the instance, including the ones the administrator is not a member of. With any other token, it collects the projects and groups where the token has the role above.

For Personal Access Tokens:

  1. Go to GitLab → User Settings → Access Tokens
  2. Create a new token with the read_api scope
  3. Note the token value securely

For Project or Group Access Tokens:

  1. Go to Project (or Group) → Settings → Access Tokens
  2. Create a token with the Maintainer role for a project, or the Owner role for a group
  3. Select the read_api scope

2. Basic Configuration​

Add the GitLab source to your ggscout configuration file:

[sources.gitlab]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}" # GitLab access token
url = "https://gitlab.com/" # Your GitLab instance URL
env = "production" # Optional: Environment label
owner = "devops-team@example.com" # Optional: Owner of this source

[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "https://api.gitguardian.com/v1"

3. Environment Variables​

Set the required environment variables:

# GitLab access token
GITLAB_CI_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

# GitGuardian API token
GITGUARDIAN_API_KEY="your-gitguardian-api-key"

Advanced Configuration​

Self-Hosted GitLab​

For self-hosted GitLab instances:

[sources.gitlab-selfhosted]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}"
url = "https://gitlab.example.com/" # Your GitLab instance URL

Multiple GitLab Instances​

You can configure multiple GitLab sources:

[sources.gitlab-saas]
type = "gitlabci"
token = "${GITLAB_SAAS_TOKEN}" # Token for GitLab.com
url = "https://gitlab.com/"

[sources.gitlab-onprem]
type = "gitlabci"
token = "${GITLAB_ONPREM_TOKEN}" # Token for self-hosted instance
url = "https://gitlab.internal.com/"

Resource Filtering​

You can filter which GitLab resources ggscout collects using include and exclude patterns:

[sources.gitlab-filtered]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}"
url = "https://gitlab.com/"
env = "production"
owner = "devops-team@example.com"

# Include only specific projects or groups
[[sources.gitlab-filtered.include]]
resource_ids = ["my-group/*", "important-project"]

# Exclude test or development projects
[[sources.gitlab-filtered.exclude]]
resource_ids = ["*/test-*", "dev-*", "sandbox/*"]

Configuration Parameters​

ParameterDescriptionRequiredExample
typeMust be "gitlabci"Yes"gitlabci"
tokenGitLab access tokenYes"${GITLAB_CI_TOKEN}"
urlGitLab instance URLYes"https://gitlab.com/"
envDefault environment of this source's secrets. GitGuardian infers a per-secret environment and falls back to this valueNo"production"
ownerOwner of this source (an email, usually of an employee or a team)No"devops-team@example.com"
include_archivedAlso collect the variables of archived projects, which can still hold working credentials (default: false)Notrue
[[sources.<name>.include]]Table of resource_id patterns to includeNoSee filtering section
[[sources.<name>.exclude]]Table of resource_id patterns to excludeNoSee filtering section

Note:

  • Use [[sources.<name>.include]] and [[sources.<name>.exclude]] tables to specify multiple include/exclude rules. Each table must have a resource_ids array.
  • Patterns support wildcards (*) only at the end for prefix matching. For exact matches, specify the complete name without wildcards.

Running ggscout​

Using Docker​

Create a .env file:

GITLAB_CI_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITGUARDIAN_API_KEY=your-gitguardian-api-key

Then run ggscout to collect GitLab data:

docker run --rm -ti \
-v ${PWD}/config.toml:/tmp/config.toml:ro \
--env-file .env \
ghcr.io/gitguardian/ggscout/chainguard:latest \
fetch-and-send /tmp/config.toml

Using Helm​

Deploy ggscout with GitLab integration using the official Helm chart:

# Add the ggscout Helm repository
helm repo add ggscout https://gitguardian.github.io/ggscout-helm-charts
helm repo update

# Create a values file for GitLab integration
cat > gitlab-values.yaml << EOF
config:
sources:
gitlab:
type: "gitlabci"
token: "${GITLAB_CI_TOKEN}"
url: "https://gitlab.com/"

gitguardian:
api_token: "${GITGUARDIAN_API_KEY}"
endpoint: "https://api.gitguardian.com/v1"

secrets:
GITLAB_CI_TOKEN: "glpat-xxxxxxxxxxxxxxxxxxxx"
GITGUARDIAN_API_KEY: "your-gitguardian-api-key"

schedule: "0 */6 * * *" # Run every 6 hours
EOF

# Install ggscout with GitLab integration
helm install ggscout-gitlab ggscout/ggscout -f gitlab-values.yaml

Data Collected​

The GitLab integration collects the following data:

  • Project Variables: CI/CD variables defined on each project
  • Group Variables: CI/CD variables defined on each group. GitLab does not return them with the project variables, so ggscout collects them separately
  • Instance Variables: CI/CD variables defined for the whole instance, with an administrator's token
  • Variable Metadata: Variable names, environment scopes, and the masked, protected, and hidden flags of each variable

A variable marked masked and hidden never has its value returned by GitLab. ggscout still inventories it by name and location, without a hash.

Archived projects are skipped unless include_archived is set.

Collecting every project with an administrator's token, include_archived, hidden variables, and the variable flags need ggscout 0.36.0 or later.

Since ggscout 0.33.0, the environment_scope of each variable is sent to GitGuardian, which reads it as the variable's environment when it names one (production, staging, and so on) and uses the source-level env otherwise. A wildcard scope (*) or a prefix scope such as review/* names no environment.

Troubleshooting​

Few or no variables are collected​

Check the role of the token against the table in GitLab Access Token. ggscout logs a warning for each project or group it cannot read, and when the token lists no project at all.

Debug Mode​

Enable debug logging to troubleshoot issues:

# Using Docker
docker run --rm -ti \
-v ${PWD}/config.toml:/tmp/config.toml:ro \
--env-file .env \
-e RUST_LOG=debug \
ghcr.io/gitguardian/ggscout/chainguard:latest \
fetch /tmp/config.toml --verbose -o /tmp/inventory.json