Configuration

Authentication

Set GITLAB_TOKEN to a group or personal access token with read_api scope. A group access token creates its own bot identity; a personal token can belong to a dedicated service account. Assign a role appropriate to the surfaces you need.

For a group access token, navigate to your GitLab group > Settings > Access tokens, create the token, and provide it through the GITLAB_TOKEN environment variable and the secrets entry below. Personal tokens can be created under your GitLab profile's access-token settings.

The collector does not call the Users API, so it does not require read_user. Adding that scope does not make hidden member 2FA fields available.

epack.yaml

stream: myorg/gitlab-posture

collectors:
  gitlab:
    source: locktivity/epack-collector-gitlab@^0.1
    config:
      group: my-organization
      level: trust
      # base_url: https://gitlab.example.com
      # include_patterns: ["backend-*"]
      # exclude_patterns: ["archived-*"]
    secrets:
      - GITLAB_TOKEN

Configuration options

Filters match name, not path_with_namespace. For example, backend-* matches a project named backend-api, regardless of its namespace. Projects in subgroups are included; projects shared into the group are excluded. Archived projects are included unless filtered out. Percentages use all included projects as their denominator.

Project filters apply to project metrics, project inventory, project webhooks, and deploy keys. Group members, group webhooks, runners, and group audit events keep their group scope. The configured group and filter patterns appear in trust output too.

Supply pattern lists as arrays of strings with valid glob syntax. Invalid globs and non-string list entries are rejected before collection begins.

Secrets

Self-managed and Dedicated instances

Set base_url to the instance URL, without an /api/v4 suffix:

config:
  group: my-org
  base_url: https://gitlab.example.com

For GitLab Dedicated, use the URL of your dedicated instance in the same way.

Roles, scopes, and tiers

Requirements vary with GitLab version. Consult the Projects API, Groups members API, Runners API, and Audit events API.

Optional endpoint failures emit diagnostics. HTTP 401 is always fatal; non-permission failures fetching the group or project list are fatal too. A successful response can omit restricted fields without a diagnostic. Group webhook and audit-event HTTP 403 diagnostics currently mention Premium even when the cause is insufficient role. Runner permission diagnostics currently mention Maintainer, although the group-list endpoint has stricter documented requirements.

Examples

Basic usage (GitLab.com)

# epack.yaml
stream: myorg/gitlab-posture

collectors:
  gitlab:
    source: locktivity/epack-collector-gitlab@^0.1
    config:
      group: my-organization
    secrets:
      - GITLAB_TOKEN

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
epack collect

Self-managed instance

collectors:
  gitlab:
    source: locktivity/epack-collector-gitlab@^0.1
    config:
      group: engineering
      base_url: https://gitlab.internal.company.com
    secrets:
      - GITLAB_TOKEN

Filtered project collection

collectors:
  gitlab:
    source: locktivity/epack-collector-gitlab@^0.1
    config:
      group: my-organization
      include_patterns:
        - "backend-*"
        - "frontend-*"
      exclude_patterns:
        - "*-archived"
    secrets:
      - GITLAB_TOKEN

Audit-level collection

Set the collection level in the collector configuration:

stream: myorg/gitlab-posture

collectors:
  gitlab:
    source: locktivity/epack-collector-gitlab@^0.1
    config:
      group: my-organization
      level: audit
    secrets:
      - GITLAB_TOKEN

epack collect

Sample trust-level output

{
  "schema_version": "1.0.0",
  "collected_at": "2026-09-18T12:00:00Z",
  "collected_at_level": "trust",
  "group": "my-organization",
  "scope": {
    "include_patterns": ["*"],
    "exclude_patterns": [],
    "projects_coverage": 100
  },
  "posture": {
    "branch_protection_coverage": 95,
    "security_features_coverage": 72
  },
  "access_control": {
    "two_factor_required": true
  },
  "branch_protection_rules": {
    "merge_request_required": 92,
    "approving_reviews": 78,
    "code_owner_approval": 45,
    "no_force_push": 95
  },
  "security_features": {
    "secret_push_protection": 60,
    "pipeline_required": 84
  }
}

This is an illustrative output. diagnostics is omitted when there are no warnings or permission errors. The 72% security-features coverage above is the mean of 60% secret push protection and 84% pipeline-required coverage. See output limitations before interpreting zeros as disabled controls.