Deploy tokens | GitLab (2024)

Creating a Deploy token
Deploy token expiration
Revoking a deploy token
Limiting scopes of a deploy token
Deploy token custom username
Usage
- Git clone a repository
- Read Container Registry images
- Push Container Registry images
- Read or pull packages
- Push or upload packages
- Group deploy token
- GitLab deploy token

Version history

Introduced in GitLab 10.7.
Moved from Settings > Repository in GitLab 12.9.
Added write_registry scope in GitLab 12.10.
Moved from Settings > CI/CD in GitLab 12.10.1.
Added package registry scopes in GitLab 13.0.

Deploy tokens allow you to download (git clone) or push and pull packages andcontainer registry images of a project without having a user and a password.

Deploy tokens can be managed by maintainers only.

Deploy tokens cannot be used with the GitLab API.

If you have a key pair, you might want to use deploy keysinstead.

Creating a Deploy token

You can create as many deploy tokens as you need from the settings of yourproject. Alternatively, you can also create group-scoped deploy tokens.

Sign in to your GitLab account.
Go to the project (or group) you want to create deploy tokens for.
Go to Settings > Repository.
Expand the Deploy tokens section.
Choose a name, expiry date (optional), and username (optional) for the token.
Choose the desired scopes.
Select Create deploy token.
Save the deploy token somewhere safe. After you leave or refreshthe page, you can’t access it again.

Deploy token expiration

Deploy tokens expire at midnight UTC on the date you define.

Revoking a deploy token

To revoke a deploy token, under the Active deploy tokens area,select the respective Revoke button.

Limiting scopes of a deploy token

Deploy tokens can be created with different scopes that allow various actionsthat a given token can perform. The available scopes are depicted in thefollowing table along with GitLab version it was introduced in:

Scope	Description	Introduced in GitLab Version
`read_repository`	Allows read-access to the repository through `git clone`	10.7
`read_registry`	Allows read-access to container registry images if a project is private and authorization is required.	10.7
`write_registry`	Allows write-access (push) to container registry.	12.10
`read_package_registry`	Allows read access to the package registry.	13.0
`write_package_registry`	Allows write access to the package registry.	13.0

Deploy token custom username

Introduced in GitLab 12.1.

The default username format is gitlab+deploy-token-{n}. Some tools orplatforms may not support this format; in this case you can specify a customusername to be used when creating the deploy token.

Usage

Git clone a repository

To download a repository using a deploy token:

Create a deploy token with read_repository as a scope.
Take note of your username and token.

git clone the project using the deploy token:

git clone https://<username>:<deploy_token>@gitlab.example.com/tanuki/awesome_project.git

Replace <username> and <deploy_token> with the proper values.

Read Container Registry images

To read the container registry images, you must:

Create a deploy token with read_registry as a scope.
Take note of your username and token.
Sign in to the GitLab Container Registry using the deploy token:

docker login -u <username> -p <deploy_token> registry.example.com

Replace <username> and <deploy_token> with the proper values. You can nowpull images from your Container Registry.

Push Container Registry images

Introduced in GitLab 12.10.

To push the container registry images, you must:

Read or pull packages

Introduced in GitLab 13.0.

To pull packages in the GitLab package registry, you must:

Create a deploy token with read_package_registry as a scope.
Take note of your username and token.
For the package type of your choice, follow theauthentication instructions for deploy tokens.

Example request publishing a NuGet package using a deploy token:

nuget source Add -Name GitLab -Source "https://gitlab.example.com/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdfnuget push mypkg.nupkg -Source GitLab

Push or upload packages

Introduced in GitLab 13.0.

To upload packages in the GitLab package registry, you must:

Create a deploy token with write_package_registry as a scope.
Take note of your username and token.
For the package type of your choice, follow theauthentication instructions for deploy tokens.

Group deploy token

Introduced in GitLab 12.9.

A deploy token created at the group level can be used across all projects thatbelong either to the specific group or to one of its subgroups.

For an overview, see Group Deploy Tokens.

The Group deploy tokens UI is now accessible under Settings > Repository,not Settings > CI/CD as indicated in the video.

To use a group deploy token:

Create a deploy token for a group.
Use it the same way you use a project deploy token whencloning a repository.

The scopes applied to a group deploy token (such as read_repository)apply consistently when cloning the repository of related projects.

GitLab deploy token

Introduced in GitLab 10.8.

There’s a special case when it comes to deploy tokens. If a user creates onenamed gitlab-deploy-token, the username and token of the deploy token isautomatically exposed to the CI/CD jobs as CI/CD variables: CI_DEPLOY_USERand CI_DEPLOY_PASSWORD, respectively.

After you create the token, you can sign in to the Container Registry by usingthose variables:

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

The special handling for the gitlab-deploy-token deploy token is notimplemented for group deploy tokens. To make the group-level deploy token available forCI/CD jobs, the CI_DEPLOY_USER and CI_DEPLOY_PASSWORD variables should be set under Settings to the name and token of the group deploy token respectively.

FAQs

What is a deploy token? ›

A deploy token is a pair of values: username: username in the HTTP authentication framework. The default username format is gitlab+deploy-token-{n} . You can specify a custom username when you create the deploy token. token: password in the HTTP authentication framework.

Read On ›

What is the difference between deploy keys and deploy tokens? ›

In most cases, you use deploy keys to access a repository from an external host, like a build server or Continuous Integration (CI) server. Depending on your needs, you might want to use a deploy token to access a repository instead. Shareable between multiple projects, even those in different groups.

Discover More Details ›

What is the difference between project access token and deploy token? ›

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.

How to get a personal access token? ›

Creating a personal access token

In the upper-right corner of any page, click your profile photo, then click Settings.
In the left sidebar, click Developer settings.
In the left sidebar, click Personal access tokens.
Click Generate new token.
In the "Note" field, give your token a descriptive name.

More items...

See Details ›

How does token authorization work? ›

Tokens are encrypted and machine-generated: Token-based authentication uses encrypted, machine-generated codes to verify a user's identity. Each token is unique to a user's session and is protected by an algorithm, which ensures servers can identify a token that has been tampered with and block it.

Find Out More ›

What are tokens used for in API? ›

Access tokens are used in token-based authentication to allow an application to access an API. The application receives an access token after a user successfully authenticates and authorizes access, then passes the access token as a credential when it calls the target API.

Tell Me More ›

What is a deploy key? ›

You can launch projects from a repository on GitHub.com to your server by using a deploy key, which is an SSH key that grants access to a single repository. GitHub attaches the public part of the key directly to your repository instead of a personal account, and the private part of the key remains on your server.

Show Me More ›

Is an API key the same as a token? ›

The main distinction between these two is: API keys identify the calling project — the application or site — making the call to an API. Authentication tokens identify a user — the person — that is using the app or site.

Explore More ›

What does deployed mean in code? ›

Deploying code is the process of moving code changes from a development environment to a production environment, where it becomes accessible to users. This typically involves a series of steps, including testing, building, and releasing the code.

What is an example of a token format? ›

Email Address. The EMAIL_ADDRESS_TOKEN format creates a token in an email format, for example: something@email.com could become mhipdwxme@ljrte.aab.

Show Me More ›

How to generate a deploy key for GitHub? ›

Create a Deploy Key on GitHub

Click on Settings, select Deploy keys, and then click on Add deploy key. Copy the key in the Key textbox and set a title to the key. You can leave Allow write access unchecked and click on Add key. Allow write access allows you to make changes to the repository using the deploy key.

Read The Full Story ›

What are API keys and tokens? ›

API keys are typically associated with specific servers the calling application is deployed on. When the application makes an API request, the server identifies the calling application by the API key. In contrast, an API token is a string of codes containing comprehensive data that identifies a specific user.

See Details ›

How do I create an API access token? ›

Navigate to the API access page in the admin UI (available at the URL /admin/api ). Use the navigation menu item "Configure" and select "API access". On the API access page, use the "New API token" button to navigate to the token creation form.

Get More Info Here ›

What is private access token? ›

Private Access Tokens are a powerful alternative that help you identify HTTP requests from legitimate devices and people without compromising their identity or personal information.

What does the JWT stand for? ›

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.

How do I create a deploy token in GitHub? ›

Set up deploy keys

On GitHub.com, navigate to the main page of the repository. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings. In the sidebar, click Deploy Keys.

View Details ›

What is the difference between API and token? ›

What is token in Active Directory? ›

Access tokens are used to connect AgilePoint NX apps to external data sources. Microsoft Azure Active Directory can be used for access tokens, but it can also be used as an authentication provider for AgilePoint NX Portal. Access tokens cannot be used to authenticate to the Portal.

Learn More ›

What is token in web service? ›

A web token is generated by a server and sent to a client. The token is attached to each client request so that the server knows the identity of the client and knows what data the client can access.

Discover More Details ›