🎚 Configuration¶

GitLab Guard provides 3 different configuration scopes in form of YAML files, loaded in the following order:

The 🧩 Default configuration
The 🏠 Site configuration, which overrides the default configuration
The 🗂️ Project configuration, which overrides the default & site configurations

Hint

The Default configuration provides all available configuration parameters, while the Site configuration & Project configuration can (partially) override those parameters.

🧩 Default configuration¶

The default configuration parameters of GitLab Guard can be found in the defaults.yml file of the confirm-gitlab-guard Python package, and it looks like this:

---
#
# ⚙️ Default settings
#
# This YAML configuration contains all the default settings, which are checked by GitLab Guard.
#
# All of these settings can be overridden in the site-specific `.gitlab-guard-site.yml`,
# resp. the project-specific `.gitlab-guard.yml` configuratino files.
#

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# 🪵 Protected branches
#
# Use the gitlab.const.AccessLevel enum names for the levels:
# https://python-gitlab.readthedocs.io/en/stable/api/gitlab.html#gitlab.const.AccessLevel
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

protected_branches:
  __default__:
    merge: MAINTAINER
    push: NO_ACCESS

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# 🏷 Protected tags
#
# Use the gitlab.const.AccessLevel enum names for the levels:
# https://python-gitlab.readthedocs.io/en/stable/api/gitlab.html#gitlab.const.AccessLevel
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

protected_tags:
  '*': MAINTAINER

# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#
# ⚙️ Settings
#
# For the overrides, the second-level key (e.g. `repository`) isn't required.
# Instead, the settings keys can be used directly (e.g. `lfs_enabled`).
#
# ✅ Correct example for the overrides:
#
#     settings:
#       lfs_enabled: true
#
# ❌ Incorrect example for the overrides:
#
#     settings:
#       repository:           # 🚫 This second-level key is not allowed / required
#         lfs_enabled: true
#
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

settings:

  #
  # 🤝 Common settings.
  #

  common:

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ General ➜ Visibility, project features, permissions
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Project visibility
    visibility: private

    # Additional options: Users can request access.
    request_access_enabled: false

    # Additional options: Require authentication to view media files.
    enforce_auth_checks_on_uploads: true

    # Issues.
    issues_enabled: true
    issues_access_level: private

    # Repository.
    repository_access_level: private

    # Container registry.
    container_registry_enabled: false
    container_registry_access_level: disabled

    # Analytics.
    analytics_access_level: disabled

    # Security and compliance.
    security_and_compliance_access_level: private

    # Wiki.
    wiki_enabled: false
    wiki_access_level: disabled

    # Snippets.
    snippets_enabled: false
    snippets_access_level: disabled

    # Package registry.
    packages_enabled: false

    # Monitor.
    monitor_access_level: disabled

    # Environments.
    environments_access_level: enabled

    # Feature flags.
    feature_flags_access_level: disabled

    # Infrastructure.
    infrastructure_access_level: disabled

    # Releases.
    releases_access_level: enabled

    # Email.
    emails_disabled: false
    # See https://gitlab.confirm.ch/confirm/infrastructure/gitlab-guard/-/issues/1.
    # show_default_award_emojis: true

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ General ➜ Service Desk
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Activate Service Desk.
    service_desk_enabled: false

  #
  # 💾 Repository settings.
  #

  repository:

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ General ➜ Visibility, project features, permissions
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Merge requests.
    merge_requests_access_level: private

    # Forks.
    forking_access_level: private

    # Git Large File Storage (LFS).
    lfs_enabled: false

    # CI/CD.
    builds_access_level: private

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ Repository ➜ Branch defaults
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Default branch.
    default_branch: main

    # Auto-close referenced issues on default branch.
    autoclose_referenced_issues: true

    # Branch name template.
    issue_branch_template: feature/%{id}-%{title}

  #
  # 🔀 Merge requests settings.
  #

  merge_requests:

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ Merge requests
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Merge method.
    merge_method: ff

    # Automatically resolve merge request diff threads when they become outdated .
    resolve_outdated_diff_discussions: true

    # Enable "Delete source branch" option by default.
    remove_source_branch_after_merge: true

    # Squash commits when merging.
    squash_option: never

    # Pipelines must succeed.
    only_allow_merge_if_pipeline_succeeds: true

    # Skipped pipelines are considered successful.
    allow_merge_on_skipped_pipeline: false

    # All threads must be resolved.
    only_allow_merge_if_all_discussions_are_resolved: true

    # Merge suggestions.
    suggestion_commit_message: null

    # Merge commit message template.
    merge_commit_template: null

    # Squash commit message template.
    squash_commit_template: null

  #
  # 🚀 CI/CD.
  #

  cicd:

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ CI/CD ➜ General pipelines
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Public pipelines.
    public_jobs: false

    # Auto-cancel redundant pipelines.
    auto_cancel_pending_pipelines: enabled

    # Prevent outdated deployment jobs.
    ci_forward_deployment_enabled: true

    # Use separate caches for protected branches.
    ci_separated_caches: true

    # CI/CD configuration file.
    ci_config_path: ''

    # Git strategy.
    build_git_strategy: fetch

    # Git shallow clone.
    ci_default_git_depth: 10

    # Timeout.
    build_timeout: 900

    # Disable or enable the ability to keep the latest artifact.
    keep_latest_artifact: False

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ CI/CD ➜ Auto DevOps
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Default to Auto DevOps pipeline.
    auto_devops_enabled: false

    # Deployment strategy.
    auto_devops_deploy_strategy: continuous

    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    # Settings ➜ CI/CD ➜ Runners
    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    # Enable instance runners for this project.
    shared_runners_enabled: true

Overrides¶

Important

The content of the 🏠 Site configuration & 🗂️ Project configuration match the defaults.yml above. However, the second-level keys of the settings dict / object (e.g. repository) isn’t required, and must be skipped.

For example, this setting from the defaults.yml…

settings:
  repository:           # 🚫 This second-level key is not allowed / required
    lfs_enabled: true

… will become this override in the site, or project configuration:

settings:
  lfs_enabled: true

🏠 Site configuration¶

Because each customer, resp. site might want to enforce its own standard, the 🧩 Default configuration can be overridden «on a site level».

GitLab Guard will automatically try to lookup the site configuration based on the following convention:

The file must be named .gitlab-guard-site.yml
The file must be placed in the current directory where GitLab Guard is executed

Hint

For the content of the .gitlab-guard-site.yml configuration, follow the description in the Overrides.

When running GitLab Guard via 🔄 GitLab CI, it’s usually enough to simply place the .gitlab-guard-site.yml in the repository of the GitLab Guard project.

🗂️ Project configuration¶

GitLab projects can override settings by providing a project-specific GitLab guard configuration file, similar to the .gitlab-ci.yml file.

GitLab Guard will automatically try to lookup the project configuration based on the following convention:

The file must be named .gitlab-guard.yml
The file must be placed in the root of the repository (not in a subdirectory)
The file must be committed on the default branch (usually main, or master)

Hint

For the content of the .gitlab-guard.yml, follow the description in the Overrides.

Important

Please note that all but one setting will be enforced by GitLab Guard. The one exception is the Repository setting, which is automatically reflected from the GitLab project settings. The reason for this is a chicken-egg issue:

To define Overrides, the repository is required – but when the repository is disabled, no overrides are possible. Thus GitLab Guard respects disabled repositories in GitLab projects.

Ignore project¶

To completely ignore a project in GitLab Guard, set the following override in the project config:

ignore: true