Skip to content

Utilize the GitLab API for creating and revoking project and group deploy tokens

Problem to solve

Deploy tokens allow to read a project repository (through git clone), or read the container registry images of a project without the need of having a user and a password. This allows users to create a single token for their project and avoid using personal access tokens. Deploy tokens can be created within the GitLab application by navigating to the project's Settings --> Repository --> Deploy Tokens.

However, for organizations with many groups, sub-groups and projects, it is inefficient and difficult to create deploy tokens for each project. Administrators need a way to easily create and revoke deploy for many groups and projects.

Customer quotes

Being able to manage deploy tokens through the API allows us to automate token generation. For example each time a new project is created we want to create a deploy token for it which Kubernetes can use to pull container images. Our current workaround is to have a separate "image pull user" with an impersonation token which is used as the pull secret, which is less than ideal.

Intended users

Further details

Project vs. Group Tokens

  • In 12.8, the progressive delivery team is planning on adding support for group deploy tokens.
  • This will add Repository as an additional navigation item to the Group settings
  • This proposal will assume that deploy tokens will be created at the group/sub-group/project level.

Benefits

  • By supporting this feature with the GitLab API, we will empower administrators at large organizations to better manage how tokens are created and revoked.

Graphql Consideration

Proposal

Create a set of new API endpoints that will allow administrators to create, list and revoke GitLab Deploy Tokens at the group/sub-group/project level.

Sample Response

{
        "id": 1,
        "name": "MyToken",
        "username": "gitlab+deploy-token-1",
        "expires_at": "2020-02-14T00:00:00.000Z",
        "token": "jMRvtPNxrn3crTAGukpZ",
        "scopes": [
            "read_repository",
            "read_registry"
        ]
    }

Proposed Endpoints

  • List all deploy keys
    • Get a list of all deploy tokens across all projects of the GitLab instance. This endpoint requires admin access.
    • GET /deploy_tokens
  • List group deploy keys
    • Get a list of a specific group's deploy tokens
    • GET /group/:id/deploy_tokens
  • List project deploy tokens
    • Get a list a projects deploy tokens
    • GET /projects/:id/deploy_tokens
  • Create a project deploy token
    • Creates a new deploy token for a project.
    • POST /projects/:id/deploy_tokens
  • Create a group deploy token
    • Creates a new deploy token for a group.
    • POST /group/:id/deploy_tokens
  • Delete a project deploy token
    • Deletes a new deploy token for a project.
    • DELETE /projects/:id/deploy_token/:token_id
  • Delete a group deploy token
    • Deletes a new deploy token for a group.
    • DELETE /group/:id/deploy_token/:token_id

Permissions and Security

  • Creation, listing and deletion of deploy tokens should be limited to maintainers and owners.

Documentation

Availability & Testing

What does success look like, and how can we measure that?

  • Success looks like we empower administrators to programattically create/revoke tokens, instead of having to use the application.

Metrics

  • Count number of events for all new API endpoints
  • Compare API vs. UI usage over time

Links / references

Edited by Tim Rizzi