Getting Started with GitLab Tokens

12 min readJun 5, 2023

Each type of token has different permissions, so it is important to choose the right token for the task you need to perform. For example, if you need to access a specific project, you would use a project access token. If you need to access all of your GitLab resources, you would use a global token.

There are ~8 types of tokens in GitLab:

Personal access tokens (PAT) are used to access your GitLab account.
Project access tokens are used to access a specific project in GitLab.
Group access tokens are used to access a specific group and all the project in a group in GitLab.
Deploy Tokens are used to grant access to other applications or services in order to read or write data to the repository.
Deploy Keys is a SSH public key used to authenticate against a Git repository.
Runner tokens are used to authenticate runners in GitLab.
CI/CD Job token are used to securely managing access to jobs from external systems and applications
Trigger token are used to trigger a job from an external service without needing to make a call to the API

1. Personal Access Token

A GitLab personal access token (PAT) is a unique string of characters that grants you access to your GitLab account. You can use a PAT to access your GitLab repositories, perform actions such as pushing and pulling code, and manage your account settings.

Benefits of using a GitLab PAT

There are several benefits to using a GitLab PAT:

Security: A PAT is more secure than your username and password because it is not stored in plain text. If your PAT is compromised, you can revoke it without having to change your username and password.
Convenience: A PAT can be used to access your GitLab repositories from any machine. This can be helpful if you work on multiple machines or if you need to access your repositories from a remote location.
Flexibility: You can choose the scopes that are granted to your PAT. This means that you can control exactly what actions the PAT can perform.

Downsides of using a GitLab PAT

There are a few downsides to using a GitLab PAT:

Loss of access: If you lose your PAT, you will lose access to your GitLab repositories until you create a new PAT.
Security: If your PAT is compromised, someone could use it to access your GitLab repositories.
Complexity: PATs can be more complex to manage than usernames and passwords.

Security considerations for using a GitLab PAT

When using a GitLab PAT, it is important to follow these security considerations:

Keep your PAT secret: Do not share your PAT with anyone.
Revoke your PAT if it is compromised: If you think your PAT has been compromised, revoke it immediately.
Use a unique PAT for each application: Do not use the same PAT for multiple applications.
Set a expiration date for your PAT: This will help to prevent unauthorised access if your PAT is compromised.

Creating a GitLab PAT

To create a GitLab PAT, follow these steps:

Go to your GitLab profile page.
Click on the Access Tokens tab.
Click on the Create personal access token button.
Enter a name for your PAT.
Select the scopes that you want to grant to your PAT.
Click on the Create token button.

Your PAT will be generated and displayed on the screen. Copy the PAT and store it in a safe place. You will not be able to see it again.

Here is an example of a good GitLab PAT design:

Code snippet

PAT: ABCD1234-EFGH-IJKL-MNOP-QRSTUVWXZY
Expiration date: 2023-06-01
Scopes: read_repository, write_repository

This PAT is strong, has an expiration date.

Using a GitLab PAT

To use a GitLab PAT, you will need to provide it to the application that you want to use it with. The application will then use the PAT to authenticate you and grant you access to your GitLab repositories.

For example, if you want to use a GitLab PAT to access your repositories from the command line, you would use the following command:

Code snippet

git clone https://<your-username>:<your-pat>@gitlab.com/<your-username>/<your-repository>.git

Replace <your-username>, <your-pat>, and <your-repository> with your own values.

This method saves your personal access token in your bash history. To avoid this, run the following command:

git clone https://<username>@gitlab.com/gitlab-org/gitlab.git

2. Group Access Token

A group access token is a unique string of characters that grants access to a GitLab group. You can use a group access token to perform actions on behalf of the group, such as creating and deleting projects, managing users, and pushing and pulling code.

Benefits of using a GitLab group access token

There are several benefits to using a GitLab group access token:

Security: A group access token is more secure than a user’s personal access token because it is not stored in plain text. If a group access token is compromised, you can revoke it without having to change the user’s password.
Convenience: A group access token can be used by multiple users. This can be helpful if you have a team of developers who need to access the same resources.
Flexibility: You can choose the scopes that are granted to a group access token. This means that you can control exactly what actions the group access token can perform.

Creating a GitLab Group Access Token

To create a GitLab group access token, follow these steps:

Go to the group settings page.
Click on the Access Tokens tab.
Click on the Create group access token button.
Enter a name for your group access token.
Select the scopes that you want to grant to your group access token.
Click on the Create token button.

Your group access token will be generated and displayed on the screen. Copy the group access token and store it in a safe place. You will not be able to see it again.

Comparison with GitLab personal access token

The main difference between a GitLab personal access token and a GitLab group access token is that a GitLab personal access token is associated with a single user, while a GitLab group access token is associated with a group of users.

Bot users for groups

Bot users for groups are GitLab-created service accounts. Each time you create a group access token, a bot user is created and added to the group. These bot users are similar to bot users for projects, except they are added to groups instead of projects. Bot users for groups:

Do not count as licensed seats.
Can have a maximum role of Owner for a group.
Have a username set to group_{group_id}_bot_{random_string}. For example, group_123_bot_9effa4563398sv321.
Have an email set to group_{group_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}. For example, group_123_bot_9effa4563398sv321@noreply.example.com.

3. Project Access Token

GitLab project access tokens allow developers to authenticate with the GitLab API, verify their identity, and give temporary access to certain resources within a project, such as files, commits, and branches.

They are especially useful when you need to access private repositories from other applications or when you want to give limited access to a project to external users.

Creating a Project Access Token

On the top bar, select Main menu > Projects and find your project.
On the left sidebar, select Settings > Access Tokens.
Enter a name. The token name is visible to any user with permissions to view the project.
Enter an expiry date for the token.
Select a role for the token.
Select the desired scopes.
Select Create project access token.

Bot users for projects

Bot users for projects are GitLab-created service accounts. Each time you create a project access token, a bot user is created and added to the project. These bot users do not count as licensed seats.

The name is set to the name of the token.
The username is set to project_{project_id}_bot_{random_string}. For example, project_098765432_bot_986719hfabhy7681.
The email is set to project_{project_id}_bot_{random_string}@noreply.{Gitlab.config.gitlab.host}. For example, project_098765432_bot_986719hfabhy7681@noreply.example.com.

Bot users for projects:

Are included in a project’s member list but cannot be modified.
Cannot be added to any other project.
Can have a maximum role of Owner for a project.

When the project access token is revoked:

The bot user is deleted.
All records are moved to a system-wide user with the username Ghost User.

4. Deploy Token

A GitLab deploy token is a set of credentials that allows you to authenticate to a specific namespace or project, granting you access to certain API endpoints.

Deploy tokens are useful for granting access to other applications or services in order to read or write data to the repository.

Common use cases include

Clone Git repositories.

$ git clone https://<username>:<deploy_token>@gitlab.example.com/xyz/project_name.git

Pull from and push to a GitLab container registry.

# Pull
$ docker login -u <username> -p <deploy_token> registry.gitlab.com
$ docker pull custom_nginx_image:v1.0

# Push
$ docker login -u <username> -p <deploy_token> registry.gitlab.com
$ docker push custom_python_image:v2.0

Pull from and push to a GitLab package registry.
Deploying an application using an automated pipeline, or
Sistributing a project securely to an external partner.
Automatically deploying builds and releases in a CI/CD process
Controlling access to sensitive data stored in the repository

They also offer a more secure way to give read-only access with limited scope, as opposed to granting access to the entire repository for a limited time.

The default username format is gitlab+deploy-token-{n}. You can specify a custom username when you create the deploy token.

You can create deploy tokens at either the project or group level:

Project deploy token: Permissions apply only to the project.
Group deploy token: Permissions apply to all projects in the group.

A GitLab deploy token is a special type of deploy token. If you create a deploy token named gitlab-deploy-token, the deploy token is automatically exposed to the CI/CD jobs as variables, for use in a CI/CD pipeline:

CI_DEPLOY_USER: Username
CI_DEPLOY_PASSWORD: Token

For example, to use a GitLab token to log in to your GitLab container registry:

docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY

Create a deploy token

Create a deploy token to automate deployment tasks that can run independently of a user account.

On the top bar, select Main menu, and:

For a project deploy token, select Projects and find your project.
For a group deploy token, select Groups and find your group.

2. On the left sidebar, select Settings > Repository.

3. Expand Deploy tokens.

4. Complete the fields, and select the desired scopes.

5. Select Create deploy token.

Record the deploy token’s values. After you leave or refresh the page, you cannot access it again.

5. Deploy Key

Use deploy keys to access repositories that are hosted in GitLab. In most cases, you use deploy keys to access a repository from an external host, like a build server or Continuous Integration (CI) server.

A GitLab deploy key is a SSH public key used to authenticate against a Git repository

Scope

You cannot change a deploy key’s scope after creating it.

A deploy key has a defined scope when it is created:

Project deploy key: Access is limited to the selected project.
Public deploy key: Access can be granted to any project in a GitLab instance.

Permissions

You can change a deploy key’s permission level after creating it. Changing a project deploy key’s permissions only applies for the current project.

A deploy key is given a permission level when it is created:

Read-only: A read-only deploy key can only read from the repository.
Read-write: A read-write deploy key can read from, and write to, the repository.

Although a deploy key is a secret that isn’t associated with a specific user, GitLab authorises the creator of the deploy key if the Git-command triggers additional processes. For example:

When a deploy key is used to push a commit to a protected branch, the creator of the deploy key must have access to the branch.
When a deploy key is used to push a commit that triggers a CI/CD pipeline, the creator of the deploy key must have access to the CI/CD resources, including protected environments and secret variables.

6. Runner Token

Runners are the agents that run your CI/CD jobs.

Runner tokens are used to authenticate when registering a runner with GitLab and to authenticate to the GitLab API to communicate with a job to achieve its tasks.

Generate an Authentication token for Group Runner

On the top bar, select Main menu > Groups and find your group.
On the left sidebar, select CI/CD > Runners.
Select New group runner.

4. Select a platform.

5. Optional. Enter configurations for the runner.

6. Select Submit.

7. Follow the instructions to register the runner from the command line.

Step 0: Install GitLab Runner on MacOS

# Download the binary for your system
sudo curl --output /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-darwin-amd64

# Give it permission to execute
sudo chmod +x /usr/local/bin/gitlab-runner

# The rest of the commands execute as the user who will run the runner
# Register the runner (steps below), then run
cd ~
gitlab-runner install
gitlab-runner start

Step 1: Copy and paste the following command into your command line to register the runner.

$ gitlab-runner register  --url https://gitlab.com  --token glrt-5b6aZ4u327H

The runner token glrt-5b6aZ4u327H displays only for a short time, and is stored in the config.toml after you register the runner. It will not be visible once the runner is registered

Step 2: Choose an executor when prompted by the command line. Executors run builds in different environments.

Step 3: (Optional): Manually verify that the runner is available to pick up jobs. This may not be needed if you manage your runner as a system or user-service

$ gitlab-runner run

Generate an Authentication token for Project Runner

Steps are same as group runner.

On the top bar, select Main menu > Projects and find your project.
On the left sidebar, select Settings > CI/CD.
Select New project runner.
Select a platform.
Optional. Enter configurations for the runner.
Select Submit.
Follow the instructions to register the runner from the command line.

7. CI/CD Job Token

When a pipeline job is about to run, GitLab generates a unique token and injects it as the CI_JOB_TOKEN.

The token has the same permissions to access the API as the user that caused the job to run.

A user can cause a job to run by taking action like

pushing a commit,
triggering a manual job, or
being the owner of a scheduled pipeline.
authenticate and clone a repository from a private project in a CI/CD job

git clone @gitlab.example.com/">https://gitlab-ci-token:${CI_JOB_TOKEN}@gitlab.example.com/<namespace>/<project>

Therefore, the user must be assigned to a role that has the required privileges.

The token is valid only while the pipeline job runs. After the job finishes, you cannot use the token anymore.

You can use a GitLab CI/CD job token to authenticate with specific API endpoints:

Package Registry
Packages API (project-level).
Container Registry (the $CI_REGISTRY_PASSWORD is $CI_JOB_TOKEN).
Container Registry API
Get job Artifacts
Get job token’s job
Pipeline triggers, using the token= parameter to trigger a multi-project pipeline.
Releases and Release links
Terraform plan

Security

> To make sure that this token doesn’t leak, GitLab:

Masks the job token in job logs
Grants permissions to the job token only when the job is running

> To make sure that this token doesn’t leak, you should also configure your runners to be secure. Avoid:

Using Docker privileged mode if the machines are re-used.
Using the shell executor when jobs run on the same machine.

If you have an insecure GitLab Runner configuration, you increase the risk that someone tries to steal tokens from other jobs.

> A job token might give extra permissions that aren’t necessary to access specific private resources. The job token scope only controls access to private projects. If an accessed project is public or internal, token scoping does not apply.

If a job token is leaked, it could potentially be used to access private data to the job token’s user. By limiting the job token access scope, private data cannot be accessed unless projects are explicitly authorized.

8. Trigger Token

A GitLab trigger token is an authentication token that allows an external service to trigger a job in a CI/CD pipeline without needing to authenticate with the GitLab API.

Trigger tokens are configured in the repository settings and can be used to make API calls to trigger a job directly.

Trigger tokens are particularly useful when you want to trigger a job from an external service without needing to make a call to the API.

Security Considerations

Revoke access to the trigger token when no longer necessary.
Rotate trigger tokens on a regular basis.
Never share the trigger token with other users, services, or applications unless needed.