Execution controls

Configuring execution controls

These variables select how the settings workflow runs: entry point behavior, backend, scope, failure mode, and output locations. All defaults are static values in defaults/main.yml.

Entry points

Entry points are selected with tasks_from — apply, discover, or restore (main runs the default apply workflow). Each entry point validates its inputs through its own argument spec.

Example invocation

- name: Apply everything declared, strictly, through the API
  ansible.builtin.include_role:
    name: primetheus.gitlab_settings
    tasks_from: apply
  vars:
    gitlab_settings_backend: api
    gitlab_settings_mode: strict
    gitlab_settings_output_file: /var/log/gitlab-settings/last-apply.json

Execution Controls Spec

gitlab_settings_backend string  Ordered mutation transport preference. api expands to REST then GraphQL; all adds Rails. A single transport or ordered list is also valid. Values: rest, graphql, rails, api, all, or an ordered list. Default: api	Example: gitlab_settings_backend: api
gitlab_settings_resource string  Scope of reconciliation. The default reconciles all declared desired state; empty scopes cost nothing. Set a narrower scope only for deliberately phased orchestration (for example: apply instance settings, create groups externally, then apply group settings). Can be one of: all, instance, users, groups, projects, runners Default: all all plans in the order instance, users, groups, projects, runners — users plan before groups and projects so a membership can reference an account created in the same run.	Example: gitlab_settings_resource: groups
gitlab_settings_mode string  Failure behavior for operations that cannot be applied (unknown fields, missing groups/projects, capabilities absent on the target). strict fails the run; compatible records a skip with a reason and continues. Can be one of: strict, compatible Default: strict	Example: gitlab_settings_mode: compatible
gitlab_settings_allow_unavailable_transports boolean  Allow a strict-mode recorded skip only when a selected transport channel is unavailable. It does not permit a backend preference that omits every capable transport. Default: false	Example: gitlab_settings_allow_unavailable_transports: true
gitlab_settings_snapshot_file string (path)  Where the discover entry point writes captured application settings. Empty disables persistence. An existing snapshot is preserved, not overwritten. Default: ""	Example: gitlab_settings_snapshot_file: /var/backups/gitlab-settings.yml
gitlab_settings_restore_file string (path) Required for restore Snapshot consumed by restore (required there) or apply. Snapshot values replace the declared values for the application fields you declare, and restore fails closed when no application fields are declared, when the snapshot is missing a declared field, or when the snapshot holds null for one (the original cannot be proven) — see the restore note in Instance Settings. Default: ""	Example: gitlab_settings_restore_file: /var/backups/gitlab-settings.yml
gitlab_settings_output_file string (path)  Controller-side path where apply persists the result document (changed labels, skipped reasons, and coverage as JSON). Empty disables persistence. Default: ""	Example: gitlab_settings_output_file: /var/log/gitlab-settings/last-apply.json
gitlab_settings_rails_host string Required for SSH Inventory hostname of the GitLab Omnibus host for the ssh_omnibus strategy. SSH connectivity, credentials, jump hosts, and host keys belong to that host's inventory configuration. Required when the strategy is ssh_omnibus. Default: ""	Example: gitlab_settings_rails_host: gitlab-omnibus-01
gitlab_settings_rails_become boolean  Escalate privileges on the Omnibus host to run gitlab-rails. Default: true	Example: gitlab_settings_rails_become: true
gitlab_settings_rails_timeout integer  Timeout in seconds for the single gitlab-rails runner execution. Size it for one Rails boot (30–60s typical) plus your batch. Default: 900	Example: gitlab_settings_rails_timeout: 1800
gitlab_settings_api_timeout integer  Positive timeout in seconds for each REST or GraphQL request (maximum 3600). Default: 30	Example: gitlab_settings_api_timeout: 45
gitlab_settings_api_retries integer  Non-negative transient request retries shared by REST and GraphQL, up to 10. Safe reads and idempotent updates may retry 429/5xx responses. A non-idempotent create or delete is never replayed after an accepted request; an uncertain outcome fails closed and requires verification. Default: 3 when omitted	Example: gitlab_settings_api_retries: 5
gitlab_settings_api_retry_delay integer  Non-negative base seconds between transient REST or GraphQL retry attempts, up to 60. Without a valid GitLab Retry-After response, retries use bounded exponential backoff. A valid Retry-After response overrides that delay; either delay is capped at 60 seconds. Default: 2 when omitted	Example: gitlab_settings_api_retry_delay: 5

Result document

apply registers gitlab_settings_apply_result (and writes it to gitlab_settings_output_file when set):

{
  "backends": ["rest", "graphql"],
  "resource": "all",
  "changed": [
    {"id": "op0001", "resource": "application_settings", "target": "application"},
    {"id": "op0002", "resource": "system_hook", "target": "system_hooks.name.audit"},
    {"id": "op0003", "resource": "group_push_rule", "target": "platform.push_rules"}
  ],
  "skipped": [
    {
      "id": "op0004",
      "resource": "group_saml_provider",
      "target": "platform.saml_provider",
      "reason": "requires the rails transport"
    }
  ],
  "coverage": [
    {"id": "op0001", "resource": "application_settings", "target": "application", "backend": "rest"},
    {"id": "op0002", "resource": "system_hook", "target": "system_hooks.name.audit", "backend": "rest"},
    {"id": "op0003", "resource": "group_push_rule", "target": "platform.push_rules", "backend": "rest"},
    {
      "id": "op0004",
      "resource": "group_saml_provider",
      "target": "platform.saml_provider",
      "skipped": true,
      "reason": "requires the rails transport"
    }
  ]
}

Each result record is bound to a planned operation by id, resource, and target. skipped entries appear only in compatible mode (in strict mode the first unappliable operation fails the run). coverage has one entry per planned operation and records either the backend that processed it or the reason it was skipped.

Discovery fact

discover overwrites gitlab_settings_capabilities for each invoking host in the current play:

gitlab_settings_capabilities:
  version: 19.2.0-ee
  revision: null
  enterprise: true
  maximum_group_depth: 20

The fact is not marked cacheable. It reports target capability metadata only; captured application settings are written separately when gitlab_settings_snapshot_file is set.