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 api scope. The read_api scope isn’t enough, because the token exchange is a POST request.

  • 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:

shell
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_TOKEN is the service account’s token from your CI secret store.
  • expires_in is 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.

  1. In your GitHub repository, add the service account’s token as a secret named AR_GITLAB_TOKEN.

  2. Add a workflow file, for example .github/workflows/artifact-registry.yml:

    yaml
    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.

  1. In Jenkins, add the service account’s token as a Secret text credential with the ID ar-gitlab-token.

  2. Add a Jenkinsfile to your repository:

    groovy
    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 runs sh steps with command tracing on, which prints each command with its variables expanded. withCredentials masks only GITLAB_TOKEN, not the exchanged AR_TOKEN, so turn tracing off first.
  • Single quotes around the script: Groovy then leaves $GITLAB_TOKEN and $AR_TOKEN for 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:

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.