API for fine-grained CI/CD job token permissions configuration

Everyone can contribute. Help move this issue forward while earning points, leveling up and collecting rewards.

Problem to solve

Customers need programmatic access to configure fine-grained CI/CD job token permissions, particularly for package registry access control. Currently, while fine-grained job token permissions can be configured through the GitLab UI, there is no REST or GraphQL API to:

  • Configure which permissions a job token has for specific resources (e.g., Maven package registry)
  • Set permission levels (e.g., read-only vs. read-write for packages)
  • Automate permission configuration as part of project setup workflows

This forces customers to either:

  • Manually configure permissions through the UI for each project
  • Use Personal Access Tokens instead of ephemeral job tokens (security anti-pattern)
  • Forego fine-grained permission controls entirely

Intended users

User experience goal

Platform engineers and DevOps teams should be able to programmatically configure fine-grained job token permissions via API (REST or GraphQL), enabling:

  • Automated project setup with appropriate security controls
  • Infrastructure-as-code approaches to CI/CD security configuration
  • Consistent permission policies across multiple projects

Proposal

Extend the existing job token scope API (#351740 (closed)) to include fine-grained permission configuration:

REST API endpoints:

GET /projects/:id/job_token_permissions
PATCH /projects/:id/job_token_permissions

GraphQL mutations:

Mutation.updateJobTokenPermissions

Example use case: Configure Maven registry permissions to allow only maintainers and job tokens to push/delete packages:

curl --request PATCH \
  --header "PRIVATE-TOKEN: <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "package_registry": {
      "maven": {
        "read": true,
        "write": "job_token_and_maintainer",
        "delete": "job_token_and_maintainer"
      }
    }
  }' \
  "https://gitlab.example.com/api/v4/projects/123/job_token_permissions"

Further details

Customer context

  • Customer wants to configure Maven registry permissions programmatically
  • Two permission models needed:
    1. Only maintainers can delete/push
    2. Maintainers + Job tokens can delete/push
  • Goal: avoid manual UI configuration, enable programmatic setup via Golang automation

Related work:

  • #351740 (closed) - REST API endpoint for job token scope (completed - provides allowlist management)
  • #572694 - Fine-grained PATs permission rollout (different token type, but similar permission model)
  • #9947 - Maven Repository Group endpoint to support sub-groups (related to Maven access, but different scope)

Permissions and Security

  • API access should require Maintainer role or above (consistent with UI permissions)
  • Permission changes should be audited
  • API should validate permission combinations to prevent security misconfigurations

Documentation

Availability & Testing

  • Should be available in all tiers where fine-grained job token permissions are available
  • Requires comprehensive API tests for permission validation
  • Integration tests with package registry access

What does success look like?

  • Customers can fully automate job token permission configuration
  • Reduced reliance on long-lived Personal Access Tokens
  • Increased adoption of fine-grained job token permissions
  • Consistent security posture across automated project creation workflows
Edited by 🤖 GitLab Bot 🤖