diff options
Diffstat (limited to 'doc/api/project_job_token_scopes.md')
| -rw-r--r-- | doc/api/project_job_token_scopes.md | 211 |
1 files changed, 211 insertions, 0 deletions
diff --git a/doc/api/project_job_token_scopes.md b/doc/api/project_job_token_scopes.md new file mode 100644 index 00000000000..c73e6ea203e --- /dev/null +++ b/doc/api/project_job_token_scopes.md @@ -0,0 +1,211 @@ +--- +stage: Verify +group: Pipeline Security +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" +--- + +# Project CI/CD job token scope API **(FREE)** + +You can read more about the [CI/CD job token](../ci/jobs/ci_job_token.md) + +NOTE: +All requests to the CI/CD job token scope API endpoint must be [authenticated](rest/index.md#authentication). +The authenticated user must have at least the Maintainer role for the project. + +## Get a project's CI/CD job token access settings + +Fetch the [CI/CD job token access settings](../ci/jobs/ci_job_token.md#configure-cicd-job-token-access) (job token scope) of a project. + +```plaintext +GET /projects/:id/job_token_scope +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `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. | + +If successful, returns [`200`](rest/index.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +|:-------------------|:--------|:----------------------| +| `inbound_enabled` | boolean | Indicates if the CI/CD job token generated in other projects has access to this project. | +| `outbound_enabled` | boolean | Indicates if the CI/CD job token generated in this project has access to other projects. [Deprecated and planned for removal in GitLab 17.0 .](../update/removals.md#limit-ci_job_token-scope-is-disabled) | + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/job_token_scope" +``` + +Example response: + +```json +{ + "inbound_enabled": true, + "outbound_enabled": false +} +``` + +## Patch a project's CI/CD job token access settings + +Patch the [**Allow access to this project with a CI_JOB_TOKEN** setting](../ci/jobs/ci_job_token.md#disable-the-job-token-scope-allowlist) (job token scope) of a project. + +```plaintext +PATCH /projects/:id/job_token_scope +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `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. | +| `enabled` | boolean | **{check-circle}** Yes | Indicates CI/CD job tokens generated in other projects have restricted access to this project. | + +If successful, returns [`204`](rest/index.md#status-codes) and no response body. + +Example request: + +```shell +curl --request PATCH \ + --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope" \ + --header 'PRIVATE-TOKEN: <your_access_token>' \ + --header 'Content-Type: application/json' \ + --data '{ "enabled": false }' +``` + +## Get a project's CI/CD job token inbound allowlist + +Fetch the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) (job token scope) of a project. + +```plaintext +GET /projects/:id/job_token_scope/allowlist +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|-----------|----------------|------------------------|-------------| +| `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. | + +This endpoint supports [offset-based pagination](rest/index.md#offset-based-pagination). + +If successful, returns [`200`](rest/index.md#status-codes) and a list of project with limited fields for each project. + +Example request: + +```shell +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/job_token_scope/allowlist" +``` + +Example response: + +```json +[ + { + "id": 4, + "description": null, + "name": "Diaspora Client", + "name_with_namespace": "Diaspora / Diaspora Client", + "path": "diaspora-client", + "path_with_namespace": "diaspora/diaspora-client", + "created_at": "2013-09-30T13:46:02Z", + "default_branch": "main", + "tag_list": [ + "example", + "disapora client" + ], + "topics": [ + "example", + "disapora client" + ], + "ssh_url_to_repo": "git@gitlab.example.com:diaspora/diaspora-client.git", + "http_url_to_repo": "https://gitlab.example.com/diaspora/diaspora-client.git", + "web_url": "https://gitlab.example.com/diaspora/diaspora-client", + "avatar_url": "https://gitlab.example.com/uploads/project/avatar/4/uploads/avatar.png", + "star_count": 0, + "last_activity_at": "2013-09-30T13:46:02Z", + "namespace": { + "id": 2, + "name": "Diaspora", + "path": "diaspora", + "kind": "group", + "full_path": "diaspora", + "parent_id": null, + "avatar_url": null, + "web_url": "https://gitlab.example.com/diaspora" + } + }, + { + ... + } +``` + +## Create a new project to a project's CI/CD job token inbound allowlist + +Add a project to the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) of a project. + +```plaintext +POST /projects/:id/job_token_scope/allowlist +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|---------------------|----------------|------------------------|-------------| +| `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. | +| `target_project_id` | integer | **{check-circle}** Yes | The ID of the project added to the CI/CD job token inbound allowlist. | + +If successful, returns [`201`](rest/index.md#status-codes) and the following response attributes: + +| Attribute | Type | Description | +|:--------------------|:--------|:----------------------| +| `source_project_id` | integer | The ID of the project whose CI/CD job token inbound allowlist is added to. | +| `target_project_id` | integer | The ID of the project that is added to the inbound allowlist of the source project. | + +Example request: + +```shell +curl --request PATCH \ + --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope" \ + --header 'PRIVATE-TOKEN: <your_access_token>' \ + --header 'Content-Type: application/json' \ + --data '{ "target_project_id": 2 }' +``` + +Example response: + +```json +{ + "source_project_id": 1, + "target_project_id": 2 +} +``` + +## Remove a project from a project's CI/CD job token inbound allowlist + +Remove a project from the [CI/CD job token inbound allowlist](../ci/jobs/ci_job_token.md#allow-access-to-your-project-with-a-job-token) of a project. + +```plaintext +DELETE /projects/:id/job_token_scope/allowlist/:target_project_id +``` + +Supported attributes: + +| Attribute | Type | Required | Description | +|---------------------|----------------|------------------------|-------------| +| `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. | +| `target_project_id` | integer | **{check-circle}** Yes | The ID of the project that is removed from the CI/CD job token inbound allowlist. | + +If successful, returns [`204`](rest/index.md#status-codes) and no response body. + +Example request: + +```shell + +curl --request DELETE \ + --url "https://gitlab.example.com/api/v4/projects/1/job_token_scope/allowlist/2" \ + --header 'PRIVATE-TOKEN: <your_access_token>' \ + --header 'Content-Type: application/json' +``` |