Skip to content

Track deployments of an external deployment tool

DETAILS: Tier: Free, Premium, Ultimate Offering:, Self-managed, GitLab Dedicated

While GitLab offers a built-in deployment solution, you might prefer to use an external deployment tool, such as Heroku or ArgoCD. GitLab can receive deployment events from these external tools and allows you to track the deployments within GitLab. For example, the following features are available by setting up tracking:

NOTE: Some of the features are not available because GitLab can't authorize and leverage those external deployments, including Protected Environments, Deployment Approvals, Deployment safety, and Environment rollback.

How to set up deployment tracking

External deployment tools usually offer a webhook to execute an additional API request when deployment state is changed. You can configure your tool to make a request to the GitLab Deployment API. Here is an overview of the event and API request flow:

NOTE: You can create a project access token for the GitLab API authentication.

Example: Track deployments of ArgoCD

You can use ArgoCD webhook to send deployment events to GitLab Deployment API. Here is an example setup that creates a success deployment record in GitLab when ArgoCD successfully deploys a new revision:

  1. Create a new webhook. You can save the following manifest file and apply it by kubectl apply -n argocd -f <manifiest-file-path>:

    apiVersion: v1
    kind: ConfigMap
      name: argocd-notifications-cm
      trigger.on-deployed: |
        - description: Application is synced and healthy. Triggered once per commit.
          oncePer: app.status.sync.revision
          - gitlab-deployment-status
          when: app.status.operationState.phase in ['Succeeded'] and == 'Healthy'
      template.gitlab-deployment-status: |
            method: POST
            path: /projects/<your-project-id>/deployments
            body: |
                "status": "success",
                "environment": "production",
                "sha": "{{.app.status.operationState.operation.sync.revision}}",
                "ref": "main",
                "tag": "false"
      service.webhook.gitlab: |
        - name: PRIVATE-TOKEN
          value: <your-access-token>
        - name: Content-type
          value: application/json
  2. Create a new subscription in your application:

    kubectl patch app <your-app-name> -n argocd -p '{"metadata": {"annotations": {"":""}}}' --type merge

NOTE: If a deployment wasn't created as expected, you can troubleshoot with argocd-notifications tool. For example, argocd-notifications template notify gitlab-deployment-status <your-app-name> --recipient gitlab:argocd-notifications triggers API request immediately and renders an error message from GitLab API server if any.