Publish and install with CI/CD pipelines outside GitLab
- Tier: Premium, Ultimate
- Offering: GitLab.com
- Status: Beta
A build that runs outside GitLab, such as in GitHub Actions or Jenkins, can publish to and install from artifact registry. The job stores a GitLab token as a secret, exchanges it for a short-lived artifact registry token, then passes that token to the package manager.
Prerequisites
A service account with a personal access token that has the
apiscope. Theread_apiscope isn’t enough, because the token exchange is aPOSTrequest.An artifact registry role for the service account:
- Artifact Contributor or higher to publish.
- Artifact Viewer or higher to install or pull.
To assign a role, see Assign a role.
The service account’s token, stored as a secret in your CI system.
In the examples on this page, replace the following placeholders:
<registry_host>: Enter the hostname from your repository’s setup instructions. To find it, go to your repository and select Setup instructions.<registry_handle>: Enter your organization’s registry handle.<repository_name>: Enter the name of your Docker or OCI repository.<npm_repository_name>: Enter the name of your npm repository.
Exchange the stored token
Send the stored GitLab token to the token exchange endpoint at the start of each job:
AR_TOKEN=$(curl -sSf -X POST \
--header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
"https://gitlab.com/api/v4/token_exchange?audience=gitlab-artifact-registry&expires_in=3600" \
| sed -E 's/.*"token":"([^"]+)".*/\1/')
test -n "$AR_TOKEN"GITLAB_TOKENis the service account’s token from your CI secret store.expires_inis the token lifetime in seconds. For the default and maximum, see token lifetime. Ask for the shortest lifetime your job needs. The token cannot be revoked before it expires.
Run the exchange in every job. Do not store the artifact registry token or pass it between jobs.
Publish from GitHub Actions
This workflow pushes a container image and publishes an npm package.
In your GitHub repository, add the service account’s token as a secret named
AR_GITLAB_TOKEN.Add a workflow file, for example
.github/workflows/artifact-registry.yml:name: Publish to artifact registry on: push: branches: [main] env: REGISTRY: <registry_host> IMAGE: <registry_host>/<registry_handle>/container/<repository_name>/app NPM_REPOSITORY: <registry_host>/<registry_handle>/npm/<npm_repository_name> jobs: publish: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Exchange the GitLab token id: ar env: GITLAB_TOKEN: ${{ secrets.AR_GITLAB_TOKEN }} run: | AR_TOKEN=$(curl -sSf -X POST \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ "https://gitlab.com/api/v4/token_exchange?audience=gitlab-artifact-registry&expires_in=3600" \ | jq -r '.token') test -n "$AR_TOKEN" test "$AR_TOKEN" != null echo "::add-mask::$AR_TOKEN" echo "token=$AR_TOKEN" >> "$GITHUB_OUTPUT" - uses: docker/login-action@v3 with: registry: ${{ env.REGISTRY }} username: __token__ password: ${{ steps.ar.outputs.token }} - uses: docker/build-push-action@v6 with: context: . push: true tags: ${{ env.IMAGE }}:${{ github.sha }} - uses: actions/setup-node@v4 with: node-version: 22 - name: Publish the npm package env: AR_TOKEN: ${{ steps.ar.outputs.token }} run: | echo "//$NPM_REPOSITORY/:_authToken=$AR_TOKEN" > .npmrc npm publish --registry "https://$NPM_REPOSITORY/"
::add-mask:: hides the artifact registry token in the job log.
Publish from Jenkins
This pipeline pushes a container image and publishes an npm package. The agent needs
curl, Docker, and Node.js.
In Jenkins, add the service account’s token as a Secret text credential with the ID
ar-gitlab-token.Add a
Jenkinsfileto your repository:pipeline { agent any environment { REGISTRY = '<registry_host>' IMAGE = '<registry_host>/<registry_handle>/container/<repository_name>/app' NPM_REPOSITORY = '<registry_host>/<registry_handle>/npm/<npm_repository_name>' } stages { stage('Publish') { steps { withCredentials([string(credentialsId: 'ar-gitlab-token', variable: 'GITLAB_TOKEN')]) { sh ''' set +x set -eu trap 'docker logout "$REGISTRY"; rm -f .npmrc' EXIT AR_TOKEN=$(curl -sSf -X POST \ --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \ "https://gitlab.com/api/v4/token_exchange?audience=gitlab-artifact-registry&expires_in=3600" \ | sed -E 's/.*"token":"([^"]+)".*/\\1/') test -n "$AR_TOKEN" echo "$AR_TOKEN" | docker login "$REGISTRY" --username __token__ --password-stdin docker build -t "$IMAGE:$GIT_COMMIT" . docker push "$IMAGE:$GIT_COMMIT" echo "//$NPM_REPOSITORY/:_authToken=$AR_TOKEN" > .npmrc npm publish --registry "https://$NPM_REPOSITORY/" ''' } } } } }
Two settings keep the tokens out of the build log:
set +x: Jenkins runsshsteps with command tracing on, which prints each command with its variables expanded.withCredentialsmasks onlyGITLAB_TOKEN, not the exchangedAR_TOKEN, so turn tracing off first.- Single quotes around the script: Groovy then leaves
$GITLAB_TOKENand$AR_TOKENfor the shell to expand, so they don’t appear in the pipeline’s history.
The trap line logs out of Docker and deletes .npmrc when the script exits, even if a step
fails, so the token doesn’t stay on a reused agent.
The \\1 is how a Groovy string writes the shell’s \1.
Install packages and pull images
The same token works for reads. After the exchange:
- Docker: run
docker pullafterdocker login. - npm: point
registry=in.npmrcat a remote or virtual repository, and add an_authTokenline for it. For more information, see Authenticate to a remote or virtual repository.
A service account that only installs needs the Artifact Viewer role.
Known issues
- The job stores a long-lived secret. The service account’s token lives in your CI system’s secret store. Rotate it before it expires. Accepting GitHub Actions OIDC tokens instead is proposed in issue 637847.
- Deploy tokens are not supported. For the full list of tokens the exchange accepts, see Supported GitLab tokens.