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

282 lines
8.7 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
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-07-28 23:09:34 +05:30
---
2021-11-11 11:23:49 +05:30
# Deploy keys API **(FREE)**
2014-09-02 18:07:02 +05:30
2021-11-11 11:23:49 +05:30
## List all deploy keys **(FREE SELF)**
2016-08-24 12:49:21 +05:30
2021-11-11 11:23:49 +05:30
Get a list of all deploy keys across all projects of the GitLab instance. This
2022-04-04 11:22:00 +05:30
endpoint requires administrator access and is not available on GitLab.com.
2016-08-24 12:49:21 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-08-24 12:49:21 +05:30
GET /deploy_keys
```
2021-12-11 22:18:48 +05:30
Supported attributes:
| Attribute | Type | Required | Description |
|:------------|:---------|:---------|:----------------------|
| `public` | boolean | **{dotted-circle}** No | Only return deploy keys that are public. Defaults to `false`. |
Example request:
2020-03-13 15:44:24 +05:30
```shell
2021-12-11 22:18:48 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/deploy_keys?public=true"
2016-08-24 12:49:21 +05:30
```
Example response:
```json
[
{
"id": 1,
"title": "Public key",
2019-09-30 21:07:59 +05:30
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
2021-12-11 22:18:48 +05:30
"fingerprint": "7f:72:08:7d:0e:47:48:ec:37:79:b2:76:68:b5:87:65",
"created_at": "2013-10-02T10:12:29Z",
"projects_with_write_access": [
{
"id": 73,
"description": null,
"name": "project2",
"name_with_namespace": "Sidney Jones / project2",
"path": "project2",
"path_with_namespace": "sidney_jones/project2",
"created_at": "2021-10-25T18:33:17.550Z"
},
{
"id": 74,
"description": null,
"name": "project3",
"name_with_namespace": "Sidney Jones / project3",
"path": "project3",
"path_with_namespace": "sidney_jones/project3",
"created_at": "2021-10-25T18:33:17.666Z"
}
]
2016-08-24 12:49:21 +05:30
},
{
"id": 3,
"title": "Another Public key",
2019-09-30 21:07:59 +05:30
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
2021-12-11 22:18:48 +05:30
"fingerprint": "64:d3:73:d4:83:70:ab:41:96:68:d5:3d:a5:b0:34:ea",
"created_at": "2013-10-02T11:12:29Z",
"projects_with_write_access": []
2016-08-24 12:49:21 +05:30
}
]
```
## List project deploy keys
2014-09-02 18:07:02 +05:30
Get a list of a project's deploy keys.
2020-04-08 14:13:33 +05:30
```plaintext
2016-08-24 12:49:21 +05:30
GET /projects/:id/deploy_keys
2014-09-02 18:07:02 +05:30
```
2016-04-02 18:10:28 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-04-02 18:10:28 +05:30
2020-03-13 15:44:24 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys"
2016-04-02 18:10:28 +05:30
```
2014-09-02 18:07:02 +05:30
2016-04-02 18:10:28 +05:30
Example response:
2014-09-02 18:07:02 +05:30
```json
[
{
"id": 1,
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
2018-03-17 18:26:18 +05:30
"created_at": "2013-10-02T10:12:29Z",
"can_push": false
2014-09-02 18:07:02 +05:30
},
{
"id": 3,
"title": "Another Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
2018-03-17 18:26:18 +05:30
"created_at": "2013-10-02T11:12:29Z",
"can_push": false
2014-09-02 18:07:02 +05:30
}
]
```
2021-11-11 11:23:49 +05:30
## Get a single deploy key
2014-09-02 18:07:02 +05:30
Get a single key.
2020-04-08 14:13:33 +05:30
```plaintext
2016-08-24 12:49:21 +05:30
GET /projects/:id/deploy_keys/:key_id
2014-09-02 18:07:02 +05:30
```
Parameters:
2016-04-02 18:10:28 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-04-02 18:10:28 +05:30
| `key_id` | integer | yes | The ID of the deploy key |
2020-03-13 15:44:24 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11"
2016-04-02 18:10:28 +05:30
```
Example response:
2014-09-02 18:07:02 +05:30
```json
{
"id": 1,
"title": "Public key",
"key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
2018-03-17 18:26:18 +05:30
"created_at": "2013-10-02T10:12:29Z",
"can_push": false
2014-09-02 18:07:02 +05:30
}
```
## Add deploy key
Creates a new deploy key for a project.
2016-04-02 18:10:28 +05:30
2021-03-08 18:12:59 +05:30
If the deploy key already exists in another project, it's joined to the current
project only if the original one is accessible by the same user.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-08-24 12:49:21 +05:30
POST /projects/:id/deploy_keys
2014-09-02 18:07:02 +05:30
```
2017-08-17 22:00:37 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2017-08-17 22:00:37 +05:30
| `title` | string | yes | New deploy key's title |
| `key` | string | yes | New deploy key |
| `can_push` | boolean | no | Can deploy key push to the project's repository |
2016-04-02 18:10:28 +05:30
2020-03-13 15:44:24 +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 '{"title": "My deploy key", "key": "ssh-rsa AAAA...", "can_push": "true"}' \
"https://gitlab.example.com/api/v4/projects/5/deploy_keys/"
2016-04-02 18:10:28 +05:30
```
2014-09-02 18:07:02 +05:30
2016-04-02 18:10:28 +05:30
Example response:
```json
{
"key" : "ssh-rsa AAAA...",
"id" : 12,
"title" : "My deploy key",
2017-08-17 22:00:37 +05:30
"can_push": true,
2016-04-02 18:10:28 +05:30
"created_at" : "2015-08-29T12:44:31.550Z"
}
```
2014-09-02 18:07:02 +05:30
2018-03-17 18:26:18 +05:30
## Update deploy key
Updates a deploy key for a project.
2020-04-08 14:13:33 +05:30
```plaintext
2018-03-17 18:26:18 +05:30
PUT /projects/:id/deploy_keys/:key_id
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2018-03-17 18:26:18 +05:30
| `title` | string | no | New deploy key's title |
| `can_push` | boolean | no | Can deploy key push to the project's repository |
2020-03-13 15:44:24 +05:30
```shell
2021-09-04 01:27:46 +05:30
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
--data '{"title": "New deploy key", "can_push": true}' "https://gitlab.example.com/api/v4/projects/5/deploy_keys/11"
2018-03-17 18:26:18 +05:30
```
Example response:
```json
{
"id": 11,
"title": "New deploy key",
"key": "ssh-rsa AAAA...",
"created_at": "2015-08-29T12:44:31.550Z",
"can_push": true
}
```
2014-09-02 18:07:02 +05:30
## Delete deploy key
2021-03-08 18:12:59 +05:30
Removes a deploy key from the project. If the deploy key is used only for this project, it's deleted from the system.
2014-09-02 18:07:02 +05:30
2020-04-08 14:13:33 +05:30
```plaintext
2016-08-24 12:49:21 +05:30
DELETE /projects/:id/deploy_keys/:key_id
2014-09-02 18:07:02 +05:30
```
2016-04-02 18:10:28 +05:30
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-04-02 18:10:28 +05:30
| `key_id` | integer | yes | The ID of the deploy key |
2020-03-13 15:44:24 +05:30
```shell
2019-02-15 15:39:39 +05:30
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/13"
2016-04-02 18:10:28 +05:30
```
2016-09-13 17:45:13 +05:30
## Enable a deploy key
Enables a deploy key for a project so this can be used. Returns the enabled key, with a status code 201 when successful.
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/deploy_keys/13/enable"
2016-09-13 17:45:13 +05:30
```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
2021-09-30 23:02:18 +05:30
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
2016-09-13 17:45:13 +05:30
| `key_id` | integer | yes | The ID of the deploy key |
Example response:
```json
{
"key" : "ssh-rsa AAAA...",
"id" : 12,
"title" : "My deploy key",
"created_at" : "2015-08-29T12:44:31.550Z"
}
```
2019-12-04 20:38:33 +05:30
2021-11-11 11:23:49 +05:30
## Add deploy keys to multiple projects
2019-10-12 21:52:04 +05:30
2021-11-11 11:23:49 +05:30
If you want to add the same deploy key to multiple projects in the same
group, this can be achieved with the API.
2019-10-12 21:52:04 +05:30
First, find the ID of the projects you're interested in, by either listing all
projects:
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects"
2019-10-12 21:52:04 +05:30
```
2019-12-04 20:38:33 +05:30
Or finding the ID of a group:
2019-10-12 21:52:04 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups"
2019-12-04 20:38:33 +05:30
```
Then listing all projects in that group (for example, group 1234):
2019-10-12 21:52:04 +05:30
2020-03-13 15:44:24 +05:30
```shell
2020-06-23 00:09:42 +05:30
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1234"
2019-10-12 21:52:04 +05:30
```
With those IDs, add the same deploy key to all:
2020-03-13 15:44:24 +05:30
```shell
2019-10-12 21:52:04 +05:30
for project_id in 321 456 987; do
2021-09-04 01:27:46 +05:30
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--header "Content-Type: application/json" \
--data '{"title": "my key", "key": "ssh-rsa AAAA..."}' \
"https://gitlab.example.com/api/v4/projects/${project_id}/deploy_keys"
2019-10-12 21:52:04 +05:30
done
```