Deploy tokens

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

Deploy tokens can be managed only by users with the Maintainer role.

Deploy tokens can’t be used with the WVS public API. However, you can use deploy tokens with some endpoints, such as those from the Package Registry.

Deploy tokens are tied to the project and stay enabled even when the user who created the token is removed from the project.

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

Creating a Deploy token

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

  1. Sign in to your WVS account.
  2. On the top bar, select My Projects > View All Projects or My Groups to find your project or group.
  3. On the left sidebar, select Project Settings > Version Control.
  4. Expand Deploy tokens.
  5. Choose a name, and optionally, an expiration date and username for the token.
  6. Choose the desired scopes.
  7. Select Create deploy token.

Save the deploy token somewhere safe. After you leave or refresh the 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:

  1. On the top bar, select My Projects > View All Projects or My Groups to find your project or group.
  2. On the left sidebar, select Project Settings > Version.
  3. Expand Deploy tokens.
  4. In the Active Deploy Tokens section, by the token you want to revoke, select Revoke.

Limiting scopes of a deploy token

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

Scope Description
read_repository Allows read-access to the repository through wvs project clone or git clone
read_registry Allows read-access to container registry images if a project is private and authorization is required.
write_registry Allows write-access (push) to container registry.
read_package_registry Allows read access to the package registry.
write_package_registry Allows write access to the package registry.

Deploy token custom username

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

Usage

Git clone a repository

To download a repository using a deploy token:

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

  3. git clone the project using the deploy token: 

    git clone https://<username>:<deploy_token>@wvs.example.io/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:

  1. Create a deploy token with read_registry as a scope.
  2. Take note of your username and token.
  3. Sign in to the WVS 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 now pull images from your Container Registry.

Push Container Registry images

To push the container registry images, you must:

  1. Create a deploy token with write_registry as a scope.
  2. Take note of your username and token.

  3. Sign in to the WVS 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 now push images to your Container Registry.

Read or pull packages

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

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

Example request publishing a NuGet package using a deploy token: 

nuget source Add -Name WVS -Source "https://wvs.example.io/api/v4/projects/10/packages/nuget/index.json" -UserName deploy-token-username -Password 12345678asdf

nuget push mypkg.nupkg -Source WVS

Push or upload packages

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

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

Group deploy token

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

To use a group deploy token:

  1. Create a deploy token for a group.
  2. Use it the same way you use a project deploy token when cloning a repository.

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

Pull images from the Dependency Proxy

To pull images from the Dependency Proxy, you must:

  1. Create a group deploy token with both read_registry and write_registry scopes.
  2. Take note of your username and token.
  3. Follow the Dependency Proxy authentication instructions.

WVS deploy token

There’s a special case when it comes to deploy tokens. If a user creates one named wvs-deploy-token, the username and token of the deploy token is automatically exposed to the CI/CD jobs as CI/CD variables: CI_DEPLOY_USER and CI_DEPLOY_PASSWORD, respectively.

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

docker login -u $CI_DEPLOY_USER -p $CI_DEPLOY_PASSWORD $CI_REGISTRY
note
The special handling for the wvs-deploy-token deploy token is not implemented for group deploy tokens. To make the group-level deploy token available for CI/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.

Troubleshooting

Group deploy tokens and LFS

A known bug prevents Group Deploy Tokens from cloning LFS objects. If you receive 404 Not Found errors and this error, use a Project Deploy Token to work around the bug: 

api error: Repository or object not found:
https://<URL-with-token>.git/info/lfs/objects/batch
Check that it exists and that you have proper access to it