🎚 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.