Getting started¶

Install the role, point it at a GitLab instance, preview a change, then make it. About fifteen minutes.

Requirements¶

On the Ansible controller:

Python 3.10 or newer
ansible-core 2.16 – 2.21

Nothing is installed on the GitLab host for the default api backend — the role talks to GitLab's API from the controller. Only the Rails backend needs access to the instance itself.

Install¶

The role and its companion collection ship from the same source tree. Build and install the collection with standard tooling:

COLLECTION_ARCHIVE="$(python3 tools/build_public_collection.py --output-dir dist)"
ansible-galaxy collection install "$COLLECTION_ARCHIVE"

The installed fully-qualified names need no ANSIBLE_LIBRARY, role pre-inclusion, copied plugins, or symlinks.

Declare a target¶

Every task takes the same target: where GitLab is, and which credential to use. Start with a personal access token that carries the api scope.

gitlab_settings_target:
  url: https://gitlab.example.com
  auth:
    type: personal_access_token
    token: "{{ vault_gitlab_token }}"

Keep credentials out of plaintext

Supply every secret through Ansible Vault or an inventory lookup. The role marks credential fields no_log, but that does not protect a token committed to a playbook.

auth.type is required. It names the kind of token, which is what lets the role decide authority boundaries, endpoint acceptance, and scope requirements before it sends anything. The full set of credential families is in Credential operations.

Check the credential first¶

This is optional, and it is one request. It tells you whether the token can actually do the work before anything is attempted:

- name: Verify the credential
  primetheus.gitlab_settings.gitlab_credential_check:
    target: "{{ gitlab_settings_target }}"
    resources: [group]
    write: true

A failure here names exactly what is wrong — an inactive token, a scope that satisfies no alternative, a token of a different kind than you declared. See verifying before you converge.

Preview a change¶

Run in check mode first. The role reports what it would change and sends no write:

- name: Preview a group change
  primetheus.gitlab_settings.gitlab_settings:
    target: "{{ gitlab_settings_target }}"
    resource: group
    identifier: platform
    settings:
      group:
        description: Platform engineering

ansible-playbook -i localhost, playbook.yml --check --diff

--diff shows the before and after of each field that differs. Write-only values such as webhook secrets never appear in a diff.

Make the change¶

Drop --check. The role reads current state, compares it, and writes only what differs. Running it again reports no change — that is the contract, not a coincidence.

ansible-playbook -i localhost, playbook.yml --diff

Two ways to use it¶

You have just used the collection: ordinary Ansible tasks, one resource at a time, composable with loop and register. Reach for it when the resource set is discovered at runtime.

The role is the other shape. It converges a whole desired-state document in one pass, which is faster for bulk configuration:

- name: Converge GitLab settings
  ansible.builtin.include_role:
    name: primetheus.gitlab_settings
    tasks_from: apply
  vars:
    gitlab_settings_resource: instance
    gitlab_settings_instance:
      application:
        account:
          signup_enabled: false

Select behaviour with tasks_from — apply, discover, or restore. There is no phase variable. Both shapes share one registry, one credential contract, and one set of capability decisions.

Where to go next¶

To…	Read
Understand what a run does, and what a skip means	Reconciling settings
Capture current settings and restore them later	Discovery, snapshot, and restore
Know why a setting used REST, GraphQL, or Rails	Backends and transports
Manage a setting with no API	Rails execution
Fix a credential error	Credential operations
Look up a field	Variable schema

Runnable, persona-oriented playbooks — instance/SRE, group owner, project team, snapshot and restore, an ephemeral lab, and a GitOps converge — are in examples/ in the source tree.