# gitlab_project – Creates/updates/deletes GitLab Projects

- Synopsis

- Requirements

- Parameters

- Examples

- Return Values

- Status

## 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 <= 1.12.1

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
api_password string |  | The password to use for authentication against the API
api_token string |  | GitLab token for logging in. aliases: login_token
api_url string |  | The resolvable endpoint for the API
api_username string |  | The username to use for authentication against the API
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

Choices:
- no
- yes ←

Whether you want to create issues or not.
Possible values are true and false.

login_password string |  | GitLab password for login_user
login_user string |  | GitLab user name.

merge_requests_enabled
boolean

Choices:
- no
- yes ←

If merge requests can be made or not.
Possible values are true and false.

name string / required |  | The name of the project
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.
server_url string |  | The URL of the GitLab server, with protocol (i.e. http or https).

snippets_enabled
boolean

Choices:
- no
- yes ←

If creating snippets should be available or not.
Possible values are true and false.

state
string

Choices:
- present ←
- absent

create or delete project.
Possible values are present and absent.

validate_certs
boolean

Choices:
- no
- yes ←

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

visibility
string

Choices:
- private ←
- internal
- public

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.
aliases: visibility_level

wiki_enabled
boolean

Choices:
- no
- yes ←

If an wiki for this project should be available or not.
Possible values are true and false.

## Examples

    - name: Delete GitLab Project
      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
      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
        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 | Returned | Description
--- | --- | ---
error string | failed | the error message returned by the GitLab API Sample: 400: path is already in use
msg string | always | Success or failure message Sample: Success
project dictionary | always | API object
result dictionary | always | json parsed response from the server

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Werner Dijkerman (@dj-wasabi)

- Guillaume Martinez (@Lunik)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.