Skip to main content

Report deployments from your pipelines

With the astrolabe source, your pipelines tell Astrolabe what they deploy: at the end of each deployment, one call, and the version shows on the component and on the Deployments page. The pipeline authenticates with a pipeline token, which can do nothing but report a deployment.

Before you start

You need to be an administrator, and Deployments must be on: see See the versions deployed. The source must be astrolabe (the default). If Argo CD deploys your applications, read Read the versions in Argo CD instead: nothing to do in your pipelines.

1. 🔑 Generate the pipeline token​

  1. In the sidebar, click Administration, then, under PLATFORM, Plugins.

  2. On the Deployments card, click Configure.

  3. At the top of the page, click the Pipeline token tab. It says No pipeline token yet: no pipeline can report a deployment.

  4. Click Generate a pipeline token.

  5. The token appears in a green box, under Copy this token now and store it as the secret ASTROLABE_PIPELINE_TOKEN of your CI: it will not be shown again. Click Copy the token.

2. 🔒 Store it in your CI​

In your CI (GitLab CI, GitHub Actions, Jenkins…), create a secret variable named ASTROLABE_PIPELINE_TOKEN and paste the token in it. Never write it in a file of your repository.

3. 🧩 Check the name of the component​

Nothing to add to the catalog: a deployment is attached to the component by its name, the metadata.name of its catalog-info.yaml. For example, for shop-api:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: shop-api
spec:
  type: service
  lifecycle: production
  owner: group:default/platform

4. 🚀 Report a deployment​

  1. Back on the Pipeline token tab, under Report a deployment from a pipeline, click Copy the call. It holds the address of your Astrolabe:

    curl -X POST "https://astrolabe.example.com/api/release-manager/pipeline/projects/$COMPONENT/environments/$ENVIRONMENT" \
      -H "Authorization: Bearer $ASTROLABE_PIPELINE_TOKEN" \
      -H "Content-Type: application/json" \
      -d "{\"version\": \"$VERSION\", \"deploymentUrl\": \"$CI_JOB_URL\"}"

  2. Paste it at the end of the deployment job of your pipeline, and give it its values:

    • COMPONENT: the name of the component in the catalog, for example shop-api;
    • ENVIRONMENT: the environment, for example production or staging — it is the name of the column;
    • VERSION: the version deployed, for example 2.4.0;
    • CI_JOB_URL: the link to the job; GitLab CI gives it under that name. You can leave it out.

  3. Run the pipeline. The call answers 201.

✅ Check​

  1. In the sidebar, click Deployments: the row of the component shows the version under its environment, for example 2.4.0 under production.

  2. Back on the Pipeline token tab, the token says when it was last used: Last used on 16/10/2026 10:11:21.

✅ That's it!

🔄 Replace or revoke the token​

The token has leaked, or someone who knew it has left:

  1. On the Pipeline token tab, click Replace the token.

  2. The window Replace the pipeline token? says The current token stops working at once: every pipeline that uses it must get the new one. Click Replace.

  3. Copy the new token and put it in the ASTROLABE_PIPELINE_TOKEN secret of each CI.

To stop every pipeline from reporting, click Revoke the token, then Revoke. The message Pipeline token revoked. appears; nothing is reported until a new token is generated.

One token for all your pipelines

Astrolabe holds one pipeline token: every CI uses the same. Generating a new one replaces the old one.

Next: Common problems with Deployments.