Fine-grained permissions for CI/CD job tokens

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
  • Status: Experiment
History

You can use fine-grained permissions to explicitly allow access to a limited set of API endpoints. These permissions are applied to the CI/CD job tokens in a specified project.

This feature is an experiment and subject to change without notice. This feature is not ready for production use. If you want to use this feature, you should test outside of production first.

Enable use of fine-grained permissions

Prerequisites:

  • You must have the Owner role for a group.

You must turn on fine-grained permissions at the group level. Then, each project in the group can apply fine-grained permissions for CI/CD job tokens to grant access to individual resources.

To enable fine-grained permissions for all projects in a group:

  1. On the left sidebar, select Search or go to and find your group.
  2. On the left sidebar, select Settings > CI/CD.
  3. Expand General pipelines.
  4. Turn on the Enable fine-grained permissions for CI/CD job tokens toggle.

Add fine-grained permissions to the job token allowlist

Prerequisites:

  • You must have at least the Maintainer role for the project.
  • You must enable the use of fine-grained permissions for a project.

You can add fine-grained permissions to groups and projects on your job token allowlist. This allows them to use job tokens to access specific project resources and more accurately control which resources are available to these groups and projects.

To add fine-grained permissions to groups or projects on the job token allowlist:

  1. On the left sidebar, select Search or go to and find your project.
  2. Select Settings > CI/CD.
  3. Expand Job token permissions.
  4. In the CI/CD job token allowlist section, select Add.
  5. From the dropdown list, select Group or project.
  6. Enter the path to an existing group or project.
  7. Select Fine-grained permissions.
  8. Grant permissions to the available API endpoints.
  9. Select Add.

GitLab adds the group or project to the job token allowlist with the specified permissions. The group or project can now access any allowed resources in the current project.

Available API endpoints

The following endpoints are available for CI/CD job tokens.

None means fine-grained permissions cannot control access to this endpoint.

Scroll table to see more →
PermissionsPermission NamesPathDescription
Deployments: Read and writeADMIN_DEPLOYMENTSDELETE /projects/:id/deployments/:deployment_idDelete a specific deployment
Deployments: Read and writeADMIN_DEPLOYMENTSPOST /projects/:id/deployments/:deployment_id/approvalApprove or reject a blocked deployment
Deployments: Read and writeADMIN_DEPLOYMENTSPUT /projects/:id/deployments/:deployment_idUpdate a deployment
Deployments: Read and write, Environments: Read and writeADMIN_DEPLOYMENTS, ADMIN_ENVIRONMENTSPOST /projects/:id/deploymentsCreate a deployment
Deployments: ReadREAD_DEPLOYMENTSGET /projects/:id/deployments/:deployment_id/merge_requestsList of merge requests associated with a deployment
Deployments: ReadREAD_DEPLOYMENTSGET /projects/:id/deployments/:deployment_idGet a specific deployment
Deployments: ReadREAD_DEPLOYMENTSGET /projects/:id/deploymentsList project deployments
Environments: Read and writeADMIN_ENVIRONMENTSDELETE /projects/:id/environments/:environment_idDelete an environment
Environments: Read and writeADMIN_ENVIRONMENTSDELETE /projects/:id/environments/review_appsDelete multiple stopped review apps
Environments: Read and writeADMIN_ENVIRONMENTSPOST /projects/:id/environments/:environment_id/stopStop an environment
Environments: Read and writeADMIN_ENVIRONMENTSPOST /projects/:id/environments/stop_staleStop stale environments
Environments: Read and writeADMIN_ENVIRONMENTSPOST /projects/:id/environmentsCreate a new environment
Environments: Read and writeADMIN_ENVIRONMENTSPUT /projects/:id/environments/:environment_idUpdate an existing environment
Environments: ReadREAD_ENVIRONMENTSGET /projects/:id/environments/:environment_idGet a specific environment
Environments: ReadREAD_ENVIRONMENTSGET /projects/:id/environmentsList environments
Jobs: Read and writeADMIN_JOBSPUT /projects/:id/pipelines/:pipeline_id/metadataUpdates pipeline metadata
Jobs: ReadREAD_JOBSGET /jobs/:id/artifactsDownload the artifacts file for job
Jobs: ReadREAD_JOBSGET /projects/:id/jobs/:job_id/artifacts/*artifact_pathDownload a specific file from artifacts archive
Jobs: ReadREAD_JOBSGET /projects/:id/jobs/:job_id/artifactsDownload the artifacts archive from a job
Jobs: ReadREAD_JOBSGET /projects/:id/jobs/artifacts/:ref_name/downloadDownload the artifacts archive from a job
Jobs: ReadREAD_JOBSGET /projects/:id/jobs/artifacts/:ref_name/raw/*artifact_pathDownload a specific file from artifacts archive from a ref
NoneDELETE /projects/:id/registry/repositories/:repository_id/tags/:tag_nameDelete repository tag
NoneDELETE /projects/:id/registry/repositories/:repository_id/tagsDelete repository tags (in bulk)
NoneDELETE /projects/:id/registry/repositories/:repository_idDelete repository
NoneGET /group/:id/-/packages/composer/*package_nameComposer packages endpoint at group level for package versions metadata
NoneGET /group/:id/-/packages/composer/p/:shaComposer packages endpoint at group level for packages list
NoneGET /group/:id/-/packages/composer/p2/*package_nameComposer v2 packages p2 endpoint at group level for package versions metadata
NoneGET /group/:id/-/packages/composer/packagesComposer packages endpoint at group level
NoneGET /groups/:id/-/packages/npm/*package_nameNPM registry metadata endpoint
NoneGET /groups/:id/-/packages/pypi/files/:sha256/*file_identifierDownload a package file from a group
NoneGET /groups/:id/-/packages/pypi/simple/*package_nameThe PyPi Simple Group Package Endpoint
NoneGET /groups/:id/-/packages/pypi/simpleThe PyPi Simple Group Index Endpoint
NoneGET /job/allowed_agentsGet current agents
NoneGET /jobGet current job using job token
NoneGET /packages/conan/v1/conans/searchSearch for packages
NoneGET /packages/conan/v1/pingPing the Conan API
NoneGET /packages/conan/v1/users/authenticateAuthenticate user against conan CLI
NoneGET /packages/conan/v1/users/check_credentialsCheck for valid user credentials per conan CLI
NoneGET /packages/npm/*package_nameNPM registry metadata endpoint
NoneGET /projects/:id/packages/conan/v1/conans/searchSearch for packages
NoneGET /projects/:id/packages/conan/v1/pingPing the Conan API
NoneGET /projects/:id/packages/conan/v1/users/authenticateAuthenticate user against conan CLI
NoneGET /projects/:id/packages/conan/v1/users/check_credentialsCheck for valid user credentials per conan CLI
NoneGET /projects/:id/packages/conan/v2/conans/searchSearch for packages
NoneGET /projects/:id/packages/conan/v2/users/check_credentialsCheck for valid user credentials per conan CLI
NoneGET /projects/:id/registry/repositories/:repository_id/tags/:tag_nameGet details about a repository tag
NoneGET /projects/:id/registry/repositories/:repository_id/tagsList tags of a repository
NoneGET /projects/:id/registry/repositoriesList container repositories within a project
NonePOST /internal/dast/site_validations/:id/transitionTransitions a DAST site validation to a new state.
Packages: Read and writeADMIN_PACKAGESDELETE /groups/:id/-/packages/npm/-/package/*package_name/dist-tags/:tagDeletes the given tag
Packages: Read and writeADMIN_PACKAGESDELETE /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channelDelete Package
Packages: Read and writeADMIN_PACKAGESDELETE /packages/npm/-/package/*package_name/dist-tags/:tagDeletes the given tag
Packages: Read and writeADMIN_PACKAGESDELETE /projects/:id/packages/:package_id/package_files/:package_file_idDelete a package file
Packages: Read and writeADMIN_PACKAGESDELETE /projects/:id/packages/:package_idDelete a project package
Packages: Read and writeADMIN_PACKAGESDELETE /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channelDelete Package
Packages: Read and writeADMIN_PACKAGESDELETE /projects/:id/packages/npm/-/package/*package_name/dist-tags/:tagDeletes the given tag
Packages: Read and writeADMIN_PACKAGESPOST /projects/:id/packages/composerComposer packages endpoint for registering packages
Packages: Read and writeADMIN_PACKAGESPOST /projects/:id/packages/pypi/authorizeAuthorize the PyPi package upload from workhorse
Packages: Read and writeADMIN_PACKAGESPOST /projects/:id/packages/pypiThe PyPi Package upload endpoint
Packages: Read and writeADMIN_PACKAGESPUT /groups/:id/-/packages/npm/-/package/*package_name/dist-tags/:tagCreate or Update the given tag for the given NPM package and version
Packages: Read and writeADMIN_PACKAGESPUT /packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/export/:file_name/authorizeWorkhorse authorize the conan recipe file
Packages: Read and writeADMIN_PACKAGESPUT /packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/export/:file_nameUpload recipe package files
Packages: Read and writeADMIN_PACKAGESPUT /packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/package/:conan_package_reference/:package_revision/:file_name/authorizeWorkhorse authorize the conan package file
Packages: Read and writeADMIN_PACKAGESPUT /packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/package/:conan_package_reference/:package_revision/:file_nameUpload package files
Packages: Read and writeADMIN_PACKAGESPUT /packages/npm/-/package/*package_name/dist-tags/:tagCreate or Update the given tag for the given NPM package and version
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/export/:file_name/authorizeWorkhorse authorize the conan recipe file
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/export/:file_nameUpload recipe package files
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/package/:conan_package_reference/:package_revision/:file_name/authorizeWorkhorse authorize the conan package file
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/package/:conan_package_reference/:package_revision/:file_nameUpload package files
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/conan/v2/conans/:package_name/:package_version/:package_username/:package_channel/revisions/:recipe_revision/files/:file_name/authorizeWorkhorse authorize the conan recipe file
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/conan/v2/conans/:package_name/:package_version/:package_username/:package_channel/revisions/:recipe_revision/files/:file_nameUpload recipe package files
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/generic/:package_name/*package_version/(*path/):file_name/authorizeWorkhorse authorize generic package file
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/generic/:package_name/*package_version/(*path/):file_nameUpload package file
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/maven/*path/:file_name/authorizeWorkhorse authorize the maven package file upload
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/maven/*path/:file_nameUpload the maven package file
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/npm/-/package/*package_name/dist-tags/:tagCreate or Update the given tag for the given NPM package and version
Packages: Read and writeADMIN_PACKAGESPUT /projects/:id/packages/npm/:package_nameCreate or deprecate NPM package
Packages: ReadREAD_PACKAGESGET /groups/:id/-/packages/maven/*path/:file_nameDownload the maven package file at a group level
Packages: ReadREAD_PACKAGESGET /groups/:id/-/packages/npm/-/package/*package_name/dist-tagsGet all tags for a given an NPM package
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/digestRecipe Digest
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/download_urlsRecipe Download Urls
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_reference/digestPackage Digest
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_reference/download_urlsPackage Download Urls
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_referencePackage Snapshot
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channelRecipe Snapshot
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/export/:file_nameDownload recipe files
Packages: ReadREAD_PACKAGESGET /packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/package/:conan_package_reference/:package_revision/:file_nameDownload package files
Packages: ReadREAD_PACKAGESGET /packages/maven/*path/:file_nameDownload the maven package file at instance level
Packages: ReadREAD_PACKAGESGET /packages/npm/-/package/*package_name/dist-tagsGet all tags for a given an NPM package
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/:package_id/package_filesList package files
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/:package_id/pipelinesGet the pipelines for a single project package
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/:package_idGet a single project package
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/composer/archives/*package_nameComposer package endpoint to download a package archive
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/digestRecipe Digest
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/download_urlsRecipe Download Urls
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_reference/digestPackage Digest
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_reference/download_urlsPackage Download Urls
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_referencePackage Snapshot
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channelRecipe Snapshot
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/export/:file_nameDownload recipe files
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v1/files/:package_name/:package_version/:package_username/:package_channel/:recipe_revision/package/:conan_package_reference/:package_revision/:file_nameDownload package files
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v2/conans/:package_name/:package_version/:package_username/:package_channel/latestGet the latest revision
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v2/conans/:package_name/:package_version/:package_username/:package_channel/revisions/:recipe_revision/files/:file_nameDownload recipe files
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/conan/v2/conans/:package_name/:package_version/:package_username/:package_channel/revisions/:recipe_revision/filesList recipe files
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/generic/:package_name/*package_version/(*path/):file_nameDownload package file
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/go/*module_name/@v/:module_version.infoVersion metadata
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/go/*module_name/@v/:module_version.modDownload module file
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/go/*module_name/@v/:module_version.zipDownload module source
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/go/*module_name/@v/listList
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/maven/*path/:file_nameDownload the maven package file at a project level
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/npm/*package_name/-/*file_nameDownload the NPM tarball
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/npm/*package_nameNPM registry metadata endpoint
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/npm/-/package/*package_name/dist-tagsGet all tags for a given an NPM package
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/pypi/files/:sha256/*file_identifierThe PyPi package download endpoint
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/pypi/simple/*package_nameThe PyPi Simple Project Package Endpoint
Packages: ReadREAD_PACKAGESGET /projects/:id/packages/pypi/simpleThe PyPi Simple Project Index Endpoint
Packages: ReadREAD_PACKAGESGET /projects/:id/packagesGet a list of project packages
Packages: ReadREAD_PACKAGESPOST /groups/:id/-/packages/npm/-/npm/v1/security/advisories/bulkNPM registry bulk advisory endpoint
Packages: ReadREAD_PACKAGESPOST /groups/:id/-/packages/npm/-/npm/v1/security/audits/quickNPM registry quick audit endpoint
Packages: ReadREAD_PACKAGESPOST /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_reference/upload_urlsPackage Upload Urls
Packages: ReadREAD_PACKAGESPOST /packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/upload_urlsRecipe Upload Urls
Packages: ReadREAD_PACKAGESPOST /packages/npm/-/npm/v1/security/advisories/bulkNPM registry bulk advisory endpoint
Packages: ReadREAD_PACKAGESPOST /packages/npm/-/npm/v1/security/audits/quickNPM registry quick audit endpoint
Packages: ReadREAD_PACKAGESPOST /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/packages/:conan_package_reference/upload_urlsPackage Upload Urls
Packages: ReadREAD_PACKAGESPOST /projects/:id/packages/conan/v1/conans/:package_name/:package_version/:package_username/:package_channel/upload_urlsRecipe Upload Urls
Packages: ReadREAD_PACKAGESPOST /projects/:id/packages/npm/-/npm/v1/security/advisories/bulkNPM registry bulk advisory endpoint
Packages: ReadREAD_PACKAGESPOST /projects/:id/packages/npm/-/npm/v1/security/audits/quickNPM registry quick audit endpoint
Releases: Read and writeADMIN_RELEASESDELETE /projects/:id/releases/:tag_name/assets/links/:link_idDelete a release link
Releases: Read and writeADMIN_RELEASESDELETE /projects/:id/releases/:tag_nameDelete a release
Releases: Read and writeADMIN_RELEASESPOST /projects/:id/catalog/publishPublish a new component project release as version to the CI/CD catalog
Releases: Read and writeADMIN_RELEASESPOST /projects/:id/releases/:tag_name/assets/linksCreate a release link
Releases: Read and writeADMIN_RELEASESPOST /projects/:id/releases/:tag_name/evidenceCollect release evidence
Releases: Read and writeADMIN_RELEASESPOST /projects/:id/releasesCreate a release
Releases: Read and writeADMIN_RELEASESPUT /projects/:id/releases/:tag_name/assets/links/:link_idUpdate a release link
Releases: Read and writeADMIN_RELEASESPUT /projects/:id/releases/:tag_nameUpdate a release
Releases: ReadREAD_RELEASESGET /projects/:id/releases/:tag_name/assets/links/:link_idGet a release link
Releases: ReadREAD_RELEASESGET /projects/:id/releases/:tag_name/assets/linksList links of a release
Releases: ReadREAD_RELEASESGET /projects/:id/releases/:tag_name/downloads/*direct_asset_pathDownload a project release asset file
Releases: ReadREAD_RELEASESGET /projects/:id/releases/:tag_nameGet a release by a tag name
Releases: ReadREAD_RELEASESGET /projects/:id/releases/permalink/latest(/)(*suffix_path)Get the latest project release
Releases: ReadREAD_RELEASESGET /projects/:id/releasesList Releases
Releases: ReadREAD_RELEASESGET /projects/:id/repository/changelogGenerates a changelog section for a release and returns it
Secure files: Read and writeADMIN_SECURE_FILESDELETE /projects/:id/secure_files/:secure_file_idRemove a secure file
Secure files: Read and writeADMIN_SECURE_FILESPOST /projects/:id/secure_filesCreate a secure file
Secure files: ReadREAD_SECURE_FILESGET /projects/:id/secure_files/:secure_file_id/downloadDownload secure file
Secure files: ReadREAD_SECURE_FILESGET /projects/:id/secure_files/:secure_file_idGet the details of a specific secure file in a project
Secure files: ReadREAD_SECURE_FILESGET /projects/:id/secure_filesGet list of secure files in a project
Terraform state: Read and writeADMIN_TERRAFORM_STATEDELETE /projects/:id/terraform/state/:name/lockUnlock a Terraform state of a certain name
Terraform state: Read and writeADMIN_TERRAFORM_STATEDELETE /projects/:id/terraform/state/:name/versions/:serialDelete a Terraform state version
Terraform state: Read and writeADMIN_TERRAFORM_STATEDELETE /projects/:id/terraform/state/:nameDelete a Terraform state of a certain name
Terraform state: Read and writeADMIN_TERRAFORM_STATEPOST /projects/:id/terraform/state/:name/lockLock a Terraform state of a certain name
Terraform state: Read and writeADMIN_TERRAFORM_STATEPOST /projects/:id/terraform/state/:nameAdd a new Terraform state or update an existing one
Terraform state: ReadREAD_TERRAFORM_STATEGET /projects/:id/terraform/state/:name/versions/:serialGet a Terraform state version
Terraform state: ReadREAD_TERRAFORM_STATEGET /projects/:id/terraform/state/:nameGet a Terraform state by its name