gitlab-org--gitlab-foss/doc/api/deploy_tokens.md

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

These endpoints require group maintainer access or higher.

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"