GitLab Repositories

Fetches information regarding GitLab repositories, including

• Repository metadata and settings
• Merge request and approval configuration
• Pipeline history and recent runs

This plugin is intended to be run as part of an aggregate agent, and will execute the policy suite for each repository.

This page is for operators who run the plugin-gitlab-repositories plugin with the CCF Agent, and for developers who write policies for it. It documents v0.1.1 and is generated from the plugin's README at v0.1.1.

Requirements

Authentication

To authenticate this plugin, you must provide a token which has at minimum the following permissions:

• read_api (recommended) or api - Required to read groups, projects, merge requests, pipelines, releases, and other repository metadata.
• read_user alone is not sufficient for this plugin. It only covers user/profile endpoints and does not grant access to group or project APIs.

The token identity must also be able to view the configured group. For private groups, this means the backing user or service account must be a member of that group with enough visibility to read the resources the plugin queries.

Configuration

plugins:
  gitlab_repos:
    token: "glpat-abc123"
    # Numeric GitLab group ID or full group path. Use "parent/subgroup" for subgroups.
    group: platform/security
    # The following items are mutually exclusive, so cannot be set together. If neither are set, all repos are
    # pulled and tested, otherwise the selection is chosen below
    included_repositories: foo,bar,baz
    excluded_repositories: quix,quiz

If group is configured as a short name instead of a numeric ID or full path, GitLab can return 404 Not Found for group-scoped endpoints. The plugin now validates the configured group up front and fails with a specific error in that case.

If group-member enumeration is inaccessible after group resolution succeeds, the plugin logs a warning and continues evaluating repositories without group_members data.

Policies

The policy bundles that work with this plugin, at their newest releases. The controls are the ones the bundle's policies list in their metadata.

Bundle	Latest version	Controls covered	Compatible plugin lines
plugin-gitlab-repositories-policies	v0.1.0	none listed	latest

When writing OPA/Rego policies for this plugin, they must be added under the compliance_framework Rego package:

# deny_critical_severity.rego
# package compliance_framework.[YOUR_RULE_PATH]
package compliance_framework.deny_critical_severity

Policy data

Any policy_data set on this plugin's block in the agent configuration is passed to every policy evaluation and is available to Rego as data.<key>:

plugins:
  gitlab_repos:
    # ...plugin settings as above...
    policy_data:
      allowed_visibility:
        - private