debian-mirror-gitlab/doc/api/deploy_tokens.md

360 lines
10 KiB
Markdown
Raw Normal View History

2020-07-28 23:09:34 +05:30
---
stage: Release
2021-02-22 17:27:13 +05:30
group: Release
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-07-28 23:09:34 +05:30
---
2021-11-11 11:23:49 +05:30
# Deploy Tokens API **(FREE)**
2020-04-08 14:13:33 +05:30
2021-11-11 11:23:49 +05:30
## List all deploy tokens **(FREE SELF)**
2020-04-08 14:13:33 +05:30
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
2022-04-04 11:22:00 +05:30
Get a list of all deploy tokens across the GitLab instance. This endpoint requires administrator access.
2020-04-08 14:13:33 +05:30
```plaintext
GET /deploy_tokens
```
2021-06-08 01:23:25 +05:30
Parameters:
| Attribute | Type | Required | Description |
|-----------|----------|------------------------|-------------|
| `active` | boolean | **{dotted-circle}** No | Limit by active status. |
2020-04-08 14:13:33 +05:30
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_tokens"
```
Example response:
```json
[
{
"id": 1,
"name": "MyToken",
"username": "gitlab+deploy-token-1",
"expires_at": "2020-02-14T00:00:00.000Z",
2021-06-08 01:23:25 +05:30
"revoked": false,
"expired": false,
2020-04-08 14:13:33 +05:30
"scopes": [
"read_repository",
"read_registry"
]
}
]
```
## Project deploy tokens
2022-04-04 11:22:00 +05:30
Project deploy token API endpoints require the Maintainer role or higher
2021-09-04 01:27:46 +05:30
for the project.
2020-04-08 14:13:33 +05:30
### List project deploy tokens
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
Get a list of a project's deploy tokens.
```plaintext
GET /projects/:id/deploy_tokens
```
Parameters:
2021-06-08 01:23:25 +05:30
| Attribute | Type | Required | Description |
|:---------------|:---------------|:-----------------------|:------------|
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding). |
2021-06-08 01:23:25 +05:30
| `active` | boolean | **{dotted-circle}** No | Limit by active status. |
2020-04-08 14:13:33 +05:30
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deploy_tokens"
```
Example response:
```json
[
{
"id": 1,
"name": "MyToken",
"username": "gitlab+deploy-token-1",
"expires_at": "2020-02-14T00:00:00.000Z",
2021-06-08 01:23:25 +05:30
"revoked": false,
"expired": false,
2020-04-08 14:13:33 +05:30
"scopes": [
"read_repository",
"read_registry"
]
}
]
```
2022-05-07 20:08:51 +05:30
### Get a project deploy token
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82467) in GitLab 14.9.
Get a single project's deploy token by ID.
```plaintext
GET /projects/:id/deploy_tokens/:token_id
```
Parameters:
| Attribute | Type | Required | Description |
| ---------- | -------------- | ---------------------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
2022-05-07 20:08:51 +05:30
| `token_id` | integer | **{check-circle}** Yes | ID of the deploy token |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deploy_tokens/1"
```
Example response:
```json
{
"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"
]
}
```
2020-04-08 14:13:33 +05:30
### Create a project deploy token
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
Creates a new deploy token for a project.
2020-04-22 19:07:51 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
POST /projects/:id/deploy_tokens
```
2021-06-08 01:23:25 +05:30
Parameters:
| Attribute | Type | Required | Description |
| ------------ | ---------------- | ---------------------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
2021-06-08 01:23:25 +05:30
| `name` | string | **{check-circle}** Yes | New deploy token's name |
| `expires_at` | datetime | **{dotted-circle}** 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 | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` |
| `scopes` | array of strings | **{check-circle}** 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:
2020-04-08 14:13:33 +05:30
```shell
2021-09-04 01:27:46 +05:30
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/"
2020-04-08 14:13:33 +05:30
```
Example response:
```json
{
"id": 1,
"name": "My deploy token",
"username": "custom-user",
"expires_at": "2021-01-01T00:00:00.000Z",
"token": "jMRvtPNxrn3crTAGukpZ",
2021-06-08 01:23:25 +05:30
"revoked": false,
"expired": false,
2020-04-08 14:13:33 +05:30
"scopes": [
"read_repository"
]
}
```
### Delete a project deploy token
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
Removes a deploy token from the project.
2020-04-22 19:07:51 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
DELETE /projects/:id/deploy_tokens/:token_id
```
2021-06-08 01:23:25 +05:30
Parameters:
| Attribute | Type | Required | Description |
| ---------- | -------------- | ---------------------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the project](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
2022-05-07 20:08:51 +05:30
| `token_id` | integer | **{check-circle}** Yes | ID of the deploy token |
2020-04-08 14:13:33 +05:30
Example request:
```shell
2021-09-04 01:27:46 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" \
"https://gitlab.example.com/api/v4/projects/5/deploy_tokens/13"
2020-04-08 14:13:33 +05:30
```
## Group deploy tokens
2022-04-04 11:22:00 +05:30
Users with at least the Maintainer role for the group can list group deploy
2022-01-26 12:08:38 +05:30
tokens. Only group Owners can create and delete group deploy tokens.
2020-04-08 14:13:33 +05:30
2020-04-22 19:07:51 +05:30
### List group deploy tokens
2020-04-08 14:13:33 +05:30
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
Get a list of a group's deploy tokens
2020-04-22 19:07:51 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
GET /groups/:id/deploy_tokens
```
Parameters:
2021-06-08 01:23:25 +05:30
| Attribute | Type | Required | Description |
|:---------------|:---------------|:-----------------------|:------------|
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding). |
2021-06-08 01:23:25 +05:30
| `active` | boolean | **{dotted-circle}** No | Limit by active status. |
2020-04-08 14:13:33 +05:30
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/deploy_tokens"
```
Example response:
```json
[
{
"id": 1,
"name": "MyToken",
"username": "gitlab+deploy-token-1",
"expires_at": "2020-02-14T00:00:00.000Z",
2021-06-08 01:23:25 +05:30
"revoked": false,
"expired": false,
2020-04-08 14:13:33 +05:30
"scopes": [
"read_repository",
"read_registry"
]
}
]
```
2022-05-07 20:08:51 +05:30
### Get a group deploy token
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/82467) in GitLab 14.9.
Get a single group's deploy token by ID.
```plaintext
GET /groups/:id/deploy_tokens/:token_id
```
Parameters:
| Attribute | Type | Required | Description |
| ----------- | -------------- | ---------------------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
2022-05-07 20:08:51 +05:30
| `token_id` | integer | **{check-circle}** Yes | ID of the deploy token |
Example request:
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/deploy_tokens/1"
```
Example response:
```json
{
"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"
]
}
```
2020-04-08 14:13:33 +05:30
### Create a group deploy token
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
Creates a new deploy token for a group.
2020-04-22 19:07:51 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
POST /groups/:id/deploy_tokens
```
2021-06-08 01:23:25 +05:30
Parameters:
| Attribute | Type | Required | Description |
| ------------ | ---- | --------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
2021-06-08 01:23:25 +05:30
| `name` | string | **{check-circle}** Yes | New deploy token's name |
| `expires_at` | datetime | **{dotted-circle}** 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 | **{dotted-circle}** No | Username for deploy token. Default is `gitlab+deploy-token-{n}` |
| `scopes` | array of strings | **{check-circle}** 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`. |
2020-04-08 14:13:33 +05:30
Example request:
```shell
2021-09-04 01:27:46 +05:30
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/"
2020-04-08 14:13:33 +05:30
```
Example response:
```json
{
"id": 1,
"name": "My deploy token",
"username": "custom-user",
"expires_at": "2021-01-01T00:00:00.000Z",
"token": "jMRvtPNxrn3crTAGukpZ",
2021-06-08 01:23:25 +05:30
"revoked": false,
"expired": false,
2020-04-08 14:13:33 +05:30
"scopes": [
"read_registry"
]
}
```
### Delete a group deploy token
2020-06-23 00:09:42 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/21811) in GitLab 12.9.
2020-04-08 14:13:33 +05:30
Removes a deploy token from the group.
2020-04-22 19:07:51 +05:30
```plaintext
2020-04-08 14:13:33 +05:30
DELETE /groups/:id/deploy_tokens/:token_id
```
2021-06-08 01:23:25 +05:30
Parameters:
| Attribute | Type | Required | Description |
| ----------- | -------------- | ---------------------- | ----------- |
2023-04-23 21:23:45 +05:30
| `id` | integer/string | **{check-circle}** Yes | ID or [URL-encoded path of the group](rest/index.md#namespaced-path-encoding) owned by the authenticated user |
2022-05-07 20:08:51 +05:30
| `token_id` | integer | **{check-circle}** Yes | ID of the deploy token |
2020-04-08 14:13:33 +05:30
Example request:
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5/deploy_tokens/13"
```