Query GitLab groups and projects with cnquery

Gather information about GitLab groups and projects with Mondoo's open source CLI, cnquery.

Mondoo's gitlab provider lets you use cnquery to query and inventory your GitLab groups and projects. You can explore group settings, project configurations, members, protected branches, merge request policies, approval rules, and webhooks.

Requirements

To analyze your GitLab environment with cnquery, you must have:

cnquery installed on your workstation
A GitLab account with access to the groups or projects you want to query
A personal access token with appropriate scopes

Configure access to GitLab

cnquery authenticates with GitLab using a personal access token. The token's level of access determines how much information cnquery can retrieve.

To learn how to create a personal access token, read Personal access tokens in the GitLab documentation. Give the personal access token these scopes:

read_api
read_repository

Set the GITLAB_TOKEN environment variable

You can supply your personal access token to cnquery using the GITLAB_TOKEN environment variable.

Linux / macOS

export GITLAB_TOKEN=<your personal access token>

Windows

$Env:GITLAB_TOKEN = "<personal-access-token>"

Connect to GitLab

Query all accessible groups

To launch a cnquery shell with access to all your GitLab groups:

cnquery shell gitlab

Query a specific group

To query a specific group:

cnquery shell gitlab --group YOUR-GROUP-NAME

Query a specific project

To query a specific project, provide both the group and project:

cnquery shell gitlab --group YOUR-GROUP-NAME --project YOUR-PROJECT-NAME

For example:

cnquery shell gitlab --group lunalectric --project mars

If you haven't set the GITLAB_TOKEN environment variable, you can pass the token directly:

cnquery shell gitlab --token YOUR-TOKEN --group lunalectric --project mars

Run queries from the command line

Instead of using the interactive shell, you can run queries directly from the command line using the -c flag:

cnquery run gitlab --group YOUR-GROUP-NAME -c "gitlab.group.projects { name visibility }"

This is useful for scripting and automation.

Discover capabilities with the `help` command

Once inside the shell, use the help command to learn what GitLab resources you can query. This command lists all the GitLab resources:

help gitlab

From the resulting list, you can drill down further. For example, enter this command to list all the GitLab group resources you can query:

help gitlab.group

Example queries

Groups

Retrieve group details:

cnquery> gitlab.group { name visibility webURL requireTwoFactorAuthentication }
gitlab.group: {
  name: "lunalectric"
  visibility: "private"
  webURL: "https://gitlab.com/lunalectric"
  requireTwoFactorAuthentication: true
}

Check group security settings:

cnquery> gitlab.group { preventForkingOutsideGroup emailsDisabled mentionsDisabled }
gitlab.group: {
  preventForkingOutsideGroup: true
  emailsDisabled: false
  mentionsDisabled: false
}

Projects

List all projects in a group:

cnquery> gitlab.group.projects
gitlab.group.projects: [
  0: gitlab.project fullName="lunalectric / mars" visibility="private" webURL="https://gitlab.com/lunalectric/mars"
  1: gitlab.project fullName="lunalectric / saturn" visibility="private" webURL="https://gitlab.com/lunalectric/saturn"
  2: gitlab.project fullName="lunalectric / venus" visibility="private" webURL="https://gitlab.com/lunalectric/venus"
]

Retrieve details about a project:

cnquery> gitlab.project { name visibility defaultBranch archived issuesEnabled wikiEnabled }
gitlab.project: {
  name: "mars"
  visibility: "private"
  defaultBranch: "main"
  archived: false
  issuesEnabled: true
  wikiEnabled: true
}

Check CI/CD runner settings:

cnquery> gitlab.project { sharedRunnersEnabled groupRunnersEnabled autoDevopsEnabled }
gitlab.project: {
  sharedRunnersEnabled: true
  groupRunnersEnabled: true
  autoDevopsEnabled: false
}

Members

List project members and their roles:

cnquery> gitlab.project.projectMembers { name username role state }
gitlab.project.projectMembers: [
  0: {
    name: "Alice Johnson"
    username: "alice"
    role: "maintainer"
    state: "active"
  }
  1: {
    name: "Bob Smith"
    username: "bob"
    role: "developer"
    state: "active"
  }
  ...
]

Merge request settings

Check merge request policies for a project:

cnquery> gitlab.project { onlyAllowMergeIfPipelineSucceeds onlyAllowMergeIfAllDiscussionsAreResolved removeSourceBranchAfterMerge allowMergeOnSkippedPipeline mergeMethod }
gitlab.project: {
  onlyAllowMergeIfPipelineSucceeds: true
  onlyAllowMergeIfAllDiscussionsAreResolved: true
  removeSourceBranchAfterMerge: true
  allowMergeOnSkippedPipeline: false
  mergeMethod: "merge"
}

Approval rules and settings

Check approval settings for a project:

cnquery> gitlab.project.approvalSettings { approvalsBeforeMerge resetApprovalsOnPush requirePasswordToApprove mergeRequestsAuthorApproval }
gitlab.project.approvalSettings: {
  approvalsBeforeMerge: 2
  resetApprovalsOnPush: true
  requirePasswordToApprove: false
  mergeRequestsAuthorApproval: false
}

List approval rules:

cnquery> gitlab.project.approvalRules { name approvalsRequired }
gitlab.project.approvalRules: [
  0: {
    name: "Default"
    approvalsRequired: 2
  }
  1: {
    name: "Security Review"
    approvalsRequired: 1
  }
  ...
]

Protected branches

List protected branches and their settings:

cnquery> gitlab.project.protectedBranches { name allowForcePush codeOwnerApproval defaultBranch }
gitlab.project.protectedBranches: [
  0: {
    name: "main"
    allowForcePush: false
    codeOwnerApproval: true
    defaultBranch: true
  }
  ...
]

Webhooks

List project webhooks:

cnquery> gitlab.project.webhooks { url sslVerification }
gitlab.project.webhooks: [
  0: {
    url: "https://hooks.example.com/gitlab"
    sslVerification: true
  }
  ...
]

Learn more

For a list of all the GitLab resources and fields you can query, read the Mondoo GitLab Resource Pack Reference.
To learn more about how the MQL query language works, read Write Effective MQL.

Query GitLab groups and projects with cnquery

On this page