Track deployments of an external deployment tool

Introduced in GitLab 12.5.

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:

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:

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