⁉️ Usage¶

🐳 Docker image¶

To get GitLab Guard, use the following Docker image:

harbor.confirm.ch/gitlab-guard/gitlab-guard

⚙️ CLI¶

GitLab Guard provides a CLI

usage: gitlab-guard [-h] [-C] [-f] [-n NAMESPACE] [-t TOKEN] [-u URL] [-v]

The guardian of GitLab projects.

options:
  -h, --help                            show this help message and exit
  -C, --colours                         display ANSI colours during logging
  -f, --fix                             fix violations automatically (alt. FIX environment variable)
  -n, --namespace NAMESPACE             GitLab namespace (alt. GITLAB_NAMESPACE environment variable)
  -t, --token TOKEN                     GitLab access token (alt. GITLAB_TOKEN environment variable)
  -u, --url URL                         GitLab URL (alt. GITLAB_URL environment variable)
  -v, --verbose                         enable verbose mode (alt. VERBOSE environment variable)

Note

For example values, check the examples in the 🌍 Environment variables below.

🌍 Environment variables¶

Instead of the ⚙️ CLI arguments, the following environment variables, resp. CI variables can be used:

Variable	Description	Example
`FIX`	Fix violations automatically (aka don’t dry run)	`yes`
`GITLAB_NAMESPACE`	The GitLab namespace path	`example/namespace/path/`
`GITLAB_TOKEN`	The GitLab access token	`glpat-1234567890abcdefghji`
`GITLAB_URL`	The GitLab base URL	`${CI_SERVER_URL}`
`VERBOSE`	Enable verbose mode (e.g. for debugging)	`yes`

🔌 GitLab integration¶

🔄 GitLab CI¶

Important

To run GitLab Guard, you must ensure the following requirements are met:

GitLab CI/CD is configured
A GitLab runner with the Docker executor is registered
Your project can access the runner with the Docker executor

If the requirements are met, GitLab Guard can be configured to run in the CI/CD pipeline.

Create a .gitlab-ci.yml file with the following content:

Run GitLab Guard:
  stage: deploy
  image: harbor.confirm.ch/gitlab-guard/gitlab-guard:latest
  script:
    - gitlab-guard -C -u ${CI_SERVER_URL} -n NAMESPACE -f
  rules:
    - if: $CI_PIPELINE_SOURCE == 'web'          # triggers when explicitly selecting «New pipeline» in the GitLab UI
    - if: $CI_PIPELINE_SOURCE == 'schedule'     # triggers when a scheduled pipeline is executed

Hint

Feel free to update the rules: according to your need, for example:

To run it on every push, remove the rules: completely.
To run it only on pushes to the main branch, use if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
To run it only when a specific CI variable is set, use if: $TRIGGER_GITLAB_GUARD

📅 Scheduling¶

If you want to run GitGuard scheduled, you can use scheduled pipelines.