community.general.gitlab_project – Creates/updates/deletes GitLab Projects

Note

This plugin is part of the community.general collection (version 3.8.3).

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.

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

Synopsis

  • When the project does not exist in GitLab, it will be created.

  • When the project does exists and state=absent, the project will be deleted.

  • When changes are made to the project, the project will be updated.

Requirements

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

  • python >= 2.7

  • python-gitlab python module

Parameters

Parameter

Comments

allow_merge_on_skipped_pipeline

boolean

added in 3.4.0 of community.general

Allow merge when skipped pipelines exist.

Choices:

  • no

  • yes

api_password

string

The password to use for authentication against the API

api_token

string

GitLab token for logging in.

api_url

string

The resolvable endpoint for the API

api_username

string

The username to use for authentication against the API

ci_config_path

string

added in 3.7.0 of community.general

Custom path to the CI configuration file for this project.

description

string

An description for the project.

group

string

Id or the full path of the group of which this projects belongs to.

import_url

string

Git repository which will be imported into gitlab.

GitLab server needs read access to this git repository.

issues_enabled

boolean

Whether you want to create issues or not.

Possible values are true and false.

Choices:

  • no

  • yes ← (default)

lfs_enabled

boolean

added in 2.0.0 of community.general

Enable Git large file systems to manages large files such as audio, video, and graphics files.

Choices:

  • no ← (default)

  • yes

merge_method

string

added in 1.0.0 of community.general

What requirements are placed upon merges.

Possible values are merge, rebase_merge merge commit with semi-linear history, ff fast-forward merges only.

Choices:

  • ff

  • merge ← (default)

  • rebase_merge

merge_requests_enabled

boolean

If merge requests can be made or not.

Possible values are true and false.

Choices:

  • no

  • yes ← (default)

name

string / required

The name of the project.

only_allow_merge_if_all_discussions_are_resolved

boolean

added in 3.4.0 of community.general

All discussions on a merge request (MR) have to be resolved.

Choices:

  • no

  • yes

only_allow_merge_if_pipeline_succeeds

boolean

added in 3.4.0 of community.general

Only allow merges if pipeline succeeded.

Choices:

  • no

  • yes

packages_enabled

boolean

added in 3.4.0 of community.general

Enable GitLab package repository.

Choices:

  • no

  • yes

path

string

The path of the project you want to create, this will be server_url/<group>/path.

If not supplied, name will be used.

remove_source_branch_after_merge

boolean

added in 3.4.0 of community.general

Remove the source branch after merge.

Choices:

  • no

  • yes

shared_runners_enabled

boolean

added in 3.7.0 of community.general

Enable shared runners for this project.

Choices:

  • no

  • yes

snippets_enabled

boolean

If creating snippets should be available or not.

Choices:

  • no

  • yes ← (default)

squash_option

string

added in 3.4.0 of community.general

Squash commits when merging.

Choices:

  • never

  • always

  • default_off

  • default_on

state

string

Create or delete project.

Possible values are present and absent.

Choices:

  • present ← (default)

  • absent

username

string

added in 3.3.0 of community.general

Used to create a personal project under a user’s name.

validate_certs

boolean

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

Choices:

  • no

  • yes ← (default)

visibility

aliases: visibility_level

string

private Project access must be granted explicitly for each user.

internal The project can be cloned by any logged in user.

public The project can be cloned without any authentication.

Choices:

  • private ← (default)

  • internal

  • public

wiki_enabled

boolean

If an wiki for this project should be available or not.

Choices:

  • no

  • yes ← (default)

Examples

- name: Create GitLab Project
  community.general.gitlab_project:
    api_url: https://gitlab.example.com/
    api_token: "{{ api_token }}"
    name: my_first_project
    group: "10481470"

- name: Delete GitLab Project
  community.general.gitlab_project:
    api_url: https://gitlab.example.com/
    api_token: "{{ access_token }}"
    validate_certs: False
    name: my_first_project
    state: absent
  delegate_to: localhost

- name: Create GitLab Project in group Ansible
  community.general.gitlab_project:
    api_url: https://gitlab.example.com/
    validate_certs: True
    api_username: dj-wasabi
    api_password: "MySecretPassword"
    name: my_first_project
    group: ansible
    issues_enabled: False
    merge_method: rebase_merge
    wiki_enabled: True
    snippets_enabled: True
    import_url: http://git.example.com/example/lab.git
    state: present
  delegate_to: localhost

Return Values

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

Key

Description

error

string

the error message returned by the GitLab API.

Returned: failed

Sample: “400: path is already in use”

msg

string

Success or failure message.

Returned: always

Sample: “Success”

project

dictionary

API object.

Returned: always

result

dictionary

json parsed response from the server.

Returned: always

Authors

  • Werner Dijkerman (@dj-wasabi)

  • Guillaume Martinez (@Lunik)