Deploy Tokens API

List all deploy tokens

Introduced in GitLab 12.9.

Get a list of all deploy tokens across the GitLab instance. This endpoint requires admin access.

GET /deploy_tokens

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"

Example response:

[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Project deploy tokens

Project deploy token API endpoints require project maintainer access or higher.

List project deploy tokens

Introduced in GitLab 12.9.

Get a list of a project’s deploy tokens.

GET /projects/:id/deploy_tokens

Parameters:

Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the project.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deploy_tokens"

Example response:

[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Create a project deploy token

Introduced in GitLab 12.9.

Creates a new deploy token for a project.

POST /projects/:id/deploy_tokens
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
name string yes New deploy token’s name
expires_at datetime no Expiration date for the deploy token. Does not expire if no value is provided.
username string no Username for deploy token. Default is gitlab+deploy-token-{n}
scopes array of strings yes Indicates the deploy token scopes. Must be at least one of read_repository, read_registry, write_registry, read_package_registry, or write_package_registry.
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/"

Example response:

{
  "id": 1,
  "name": "My deploy token",
  "username": "custom-user",
  "expires_at": "2021-01-01T00:00:00.000Z",
  "token": "jMRvtPNxrn3crTAGukpZ",
  "scopes": [
    "read_repository"
  ]
}

Delete a project deploy token

Introduced in GitLab 12.9.

Removes a deploy token from the project.

DELETE /projects/:id/deploy_tokens/:token_id
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
token_id integer yes The ID of the deploy token

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_tokens/13"

Group deploy tokens

Group maintainers and owners can list group deploy tokens. Only group owners can create and delete group deploy tokens.

List group deploy tokens

Introduced in GitLab 12.9.

Get a list of a group’s deploy tokens

GET /groups/:id/deploy_tokens

Parameters:

Attribute Type Required Description
id integer/string yes ID or URL-encoded path of the project.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/deploy_tokens"

Example response:

[
  {
    "id": 1,
    "name": "MyToken",
    "username": "gitlab+deploy-token-1",
    "expires_at": "2020-02-14T00:00:00.000Z",
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Create a group deploy token

Introduced in GitLab 12.9.

Creates a new deploy token for a group.

POST /groups/:id/deploy_tokens
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the group owned by the authenticated user
name string yes New deploy token’s name
expires_at datetime no Expiration date for the deploy token. Does not expire if no value is provided.
username string no Username for deploy token. Default is gitlab+deploy-token-{n}
scopes array of strings yes Indicates the deploy token scopes. Must be at least one of read_repository, read_registry, write_registry, read_package_registry, or write_package_registry.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" --data '{"name": "My deploy token", "expires_at": "2021-01-01", "username": "custom-user", "scopes": ["read_repository"]}' "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/"

Example response:

{
  "id": 1,
  "name": "My deploy token",
  "username": "custom-user",
  "expires_at": "2021-01-01T00:00:00.000Z",
  "token": "jMRvtPNxrn3crTAGukpZ",
  "scopes": [
    "read_registry"
  ]
}

Delete a group deploy token

Introduced in GitLab 12.9.

Removes a deploy token from the group.

DELETE /groups/:id/deploy_tokens/:token_id
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
token_id integer yes The ID of the deploy token

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/13"