GitLab - Create A Project Access Token

This tutorial will show you how to create a "Project access token" (often referred to as a "deploy token"), which grants access to a specific project.

Since these tokens are tied to a project, rather than to a user, they may not get revoked if an administrator was to ban/block/delete the user that created them. It also means the token is rather more restricted, only gaining access to one project instead of all the projects the user has access to.

Different From Deploy Keys

Project access tokens are similar to deploy keys, which are SSH keys that grant read (and possibly write) access to a repository. The crucial differences are that "deploy keys" are SSH keys, rather than token strings. Thus, they can be used to clone the repository using git over SSH, but can't be used for pulling from the Gitlab registry, which requires a username and password. Project access tokens can still clone a repository, using git over HTTPS (which this tutorial will show you), but also be used to authenticate with the Docker repository (e.g. docker login), in order to pull down images (which this tutorial will also show you).

Related Posts

• GitLab - Create Personal Access Token
• GitLab Documentation Index

Steps

Navigate to your poject and click on Settings and then hen click on Access Tokens

1. Give a name for your token to remember it by. This is important for if you ever need to revoke it for security reasons (e.g. will know which one to revoke).
2. Click on the expiration date field to set an expiry date (defaults to one month), or click the x icon to prevent the token from ever expiring.
3. Set the role for the token. You almost certainly want to put a level higher than guest, as guest won't have permission to read from a private docker registry etc.
4. Set the access level the token provides.
   • If you wish to simply git clone the repository and not make changes, you need read_repository.
   • If you wish to be able to also push to the repository with the token, then you also need write_repository.
   • If you wish to pull from the registry for the built docker images, you need read_registry, which only appears if you have the registry enabled for the project, which is why it doesn't appear in this screenshot.
5. Click Create project access token

1. You will be taken to the project access token overview page, and you will have this one time only, to click the eye icon (1) to review the actual token, or click on the clipboard icon to copy it to your clipboard. You will not be able to revrieve it later.

2. The token will also appear in the list.

3. At any point, you can click the bin/trash icon to remove/revoke the token.

Usage

Clone Respository

Once you have generated a project access token, you can use it to clone a repository with git clone like below (substituting out the {} variables).

git clone https://{deploy-key-name}:{deploy-key-token}@gitlab.mydomain.com/my-group/my-project-name.git

Once cloned this way, you can perform pulls which will continue to use that token.

Pull Docker Image

If you set the read_registry permission, you can authenticate with the registry in order to pull the built Docker images.

Run the following command on the server in order to register the authentication details:

docker login

When prompted for the username, it is:

gitlab+deploy-token-{TOKEN_NAME_HERE}

... so for example, my token that I named my-token, would have the username:

gitlab+deploy-token-my-token

The password is the token/secret you were given when you created the token.

You should now be able to perform docker pull operations against your Gitlab registry (as long as there is nothing else like a firewall blocking you).

References

• Gitlab Docs - Deploy Tokens