Deploy Tokens API

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

List all deploy tokens

Tier: Free, Premium, Ultimate
Offering: GitLab Self-Managed, GitLab Dedicated

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

GET /deploy_tokens

Parameters:

Attribute	Type	Required	Description
`active`	boolean	No	Limit by active status.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Project deploy tokens

Project deploy token API endpoints require at least the Maintainer role for the project.

List project deploy tokens

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.
`active`	boolean	No	Limit by active status.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "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",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Get a project deploy token

Get a single project’s deploy token by ID.

GET /projects/:id/deploy_tokens/:token_id

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project
`token_id`	integer	Yes	ID of the deploy token

Example request:

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

Example response:

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

Create a project deploy token

Creates a new deploy token for a project.

POST /projects/:id/deploy_tokens

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project
`name`	string	Yes	New deploy token’s name
`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`.
`expires_at`	datetime	No	Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`)
`username`	string	No	Username for deploy token. Default is `gitlab+deploy-token-{n}`

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"]}' \
  --url "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",
  "revoked": false,
  "expired": false,
  "scopes": [
    "read_repository"
  ]
}

Delete a project deploy token

Removes a deploy token from the project.

DELETE /projects/:id/deploy_tokens/:token_id

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the project
`token_id`	integer	Yes	ID of the deploy token

Example request:

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

Group deploy tokens

Users with at least the Maintainer role for the group can list group deploy tokens. Only group Owners can create and delete group deploy tokens.

List group deploy tokens

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 group.
`active`	boolean	No	Limit by active status.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url"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",
    "revoked": false,
    "expired": false,
    "scopes": [
      "read_repository",
      "read_registry"
    ]
  }
]

Get a group deploy token

Get a single group’s deploy token by ID.

GET /groups/:id/deploy_tokens/:token_id

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the group
`token_id`	integer	Yes	ID of the deploy token

Example request:

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

Example response:

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

Create a group deploy token

Creates a new deploy token for a group.

POST /groups/:id/deploy_tokens

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the group
`name`	string	Yes	New deploy token’s name
`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`.
`expires_at`	datetime	No	Expiration date for the deploy token. Does not expire if no value is provided. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`)
`username`	string	No	Username for deploy token. Default is `gitlab+deploy-token-{n}`

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"]}' \
  --url "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",
  "revoked": false,
  "expired": false,
  "scopes": [
    "read_registry"
  ]
}

Delete a group deploy token

Removes a deploy token from the group.

DELETE /groups/:id/deploy_tokens/:token_id

Parameters:

Attribute	Type	Required	Description
`id`	integer/string	Yes	ID or URL-encoded path of the group
`token_id`	integer	Yes	ID of the deploy token

Example request:

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

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Deploy Tokens API

List all deploy tokens

Project deploy tokens

List project deploy tokens

Get a project deploy token

Create a project deploy token

Delete a project deploy token

Group deploy tokens

List group deploy tokens

Get a group deploy token

Create a group deploy token

Delete a group deploy token

Help & feedback

Docs

Product

Feature availability and product trials

Get help