Skip to content

primetheus.gitlab_settings

GitLab settings as code. An Ansible role and companion collection that reconciles instance, user, group, project, and runner settings over GitLab's REST API, GraphQL API, and — where no API exists — the Rails console.

You declare the settings you want. The role decides which transport can serve each one, checks that your credential is allowed to perform it before sending anything, and converges only what differs.

Start here

  • Getting started

    Install it, point it at an instance, and change one setting safely.

  • Credential operations

    Declare a credential, verify it before a play changes anything, and clear every state the role can report.

  • Reconciling settings

    Strict and compatible modes, check and diff, idempotence, and what a skip means.

  • Backends and transports

    How REST, GraphQL, and Rails are chosen per resource, and what to do when a resource needs one you did not enable.

The two ways to use it

As a role, for bulk convergence of a desired-state document:

- name: Converge GitLab settings
  ansible.builtin.include_role:
    name: gitlab_settings
    tasks_from: apply

As a collection, for ordinary Ansible composition when the resource set is discovered at runtime:

- name: Reconcile one group
  primetheus.gitlab_settings.gitlab_settings:
    target: "{{ gitlab_settings_target }}"
    resource: group
    identifier: platform
    settings:
      duo:
        duo_features_enabled: true

Both share one registry, one credential contract, and one set of capability decisions. See the public task interface for when to reach for which.

What the role guarantees

  • Nothing is sent that the registry has not approved. Credential family, authority boundary, and endpoint acceptance are checked before a request is built, at no network cost.
  • No silent fallback. A refused credential is never downgraded, and a transport you did not enable is never substituted.
  • Check mode is honest. A dry run reports what it would change and performs no credential maintenance.
  • Secrets stay out of output. Diagnostics carry types, reasons, and expiries — never a token, cookie, or store path.

Finding your way

If you want to… Read
Get something working Getting started
Understand a credential error Credential operations
Know why a resource was skipped Backends and transports
Capture and restore settings Discovery, snapshot, and restore
Manage settings with no API Rails execution
Look up a field Variable schema
Know why it is built this way The ADRs, in the repository under docs/adr/