community.general.gitlab_project_access_token module – Manages GitLab project access tokens

Note

This module is part of the community.general collection (version 8.6.8).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.gitlab_project_access_token.

New in community.general 8.4.0

Synopsis

  • Creates and revokes project access tokens.

Requirements

The below requirements are needed on the host that executes this module.

Parameters

Parameter

Comments

access_level

string

Access level of the access token.

Choices:

  • "guest"

  • "reporter"

  • "developer"

  • "maintainer" ← (default)

  • "owner"

api_job_token

string

added in community.general 4.2.0

GitLab CI job token for logging in.

api_oauth_token

string

added in community.general 4.2.0

GitLab OAuth token for logging in.

api_password

string

The password to use for authentication against the API.

api_token

string

GitLab access token with API permissions.

api_url

string

The resolvable endpoint for the API.

api_username

string

The username to use for authentication against the API.

ca_path

string

added in community.general 8.1.0

The CA certificates bundle to use to verify GitLab server certificate.

expires_at

string / required

Expiration date of the access token in YYYY-MM-DD format.

Make sure to quote this value in YAML to ensure it is kept as a string and not interpreted as a YAML date.

name

string / required

Access token’s name.

project

string / required

ID or full path of project in the form of group/name.

recreate

string

Whether the access token will be recreated if it already exists.

When never the token will never be recreated.

When always the token will always be recreated.

When state_change the token will be recreated if there is a difference between desired state and actual state.

Choices:

  • "never" ← (default)

  • "always"

  • "state_change"

scopes

aliases: scope

list / elements=string / required

Scope of the access token.

Choices:

  • "api"

  • "read_api"

  • "read_registry"

  • "write_registry"

  • "read_repository"

  • "write_repository"

  • "create_runner"

  • "ai_features"

  • "k8s_proxy"

state

string

When present the access token will be added to the project if it does not exist.

When absent it will be removed from the project if it exists.

Choices:

  • "present" ← (default)

  • "absent"

validate_certs

boolean

Whether or not to validate SSL certs when supplying a HTTPS endpoint.

Choices:

  • false

  • true ← (default)

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • Access tokens can not be changed. If a parameter needs to be changed, an acceess token has to be recreated. Whether tokens will be recreated is controlled by the recreate option, which defaults to never.

  • Token string is contained in the result only when access token is created or recreated. It can not be fetched afterwards.

  • Token matching is done by comparing name option.

Examples

- name: "Creating a project access token"
  community.general.gitlab_project_access_token:
    api_url: https://gitlab.example.com/
    api_token: "somegitlabapitoken"
    project: "my_group/my_project"
    name: "project_token"
    expires_at: "2024-12-31"
    access_level: developer
    scopes:
      - api
      - read_api
      - read_repository
      - write_repository
    state: present

- name: "Revoking a project access token"
  community.general.gitlab_project_access_token:
    api_url: https://gitlab.example.com/
    api_token: "somegitlabapitoken"
    project: "my_group/my_project"
    name: "project_token"
    expires_at: "2024-12-31"
    scopes:
      - api
      - read_api
      - read_repository
      - write_repository
    state: absent

- name: "Change (recreate) existing token if its actual state is different than desired state"
  community.general.gitlab_project_access_token:
    api_url: https://gitlab.example.com/
    api_token: "somegitlabapitoken"
    project: "my_group/my_project"
    name: "project_token"
    expires_at: "2024-12-31"
    scopes:
      - api
      - read_api
      - read_repository
      - write_repository
    recreate: state_change
    state: present

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

access_token

dictionary

API object.

Only contains the value of the token if the token was created or recreated.

Returned: success and state=present

Authors

  • Zoran Krleza (@pixslx)