• How to set up deployment tracking
  • Example: Track deployments of ArgoCD

Track deployments of an external deployment tool

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:

• See when an merge request has been deployed, and to which environment.
• Filter merge requests by environment or deployment date.
• DevOps Research and Assessment (DORA) metrics.
• View environments and deployments.
• Track newly included merge requests per deployment.

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:

• When a deployment starts running, create a deployment with running status.
• When a deployment succeeds, update the deployment status to success.
• When a deployment fails, update the deployment status to failed.

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
   metadata:
     name: argocd-notifications-cm
   data:
     trigger.on-deployed: |
       - description: Application is synced and healthy. Triggered once per commit.
         oncePer: app.status.sync.revision
         send:
         - gitlab-deployment-status
         when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy'
     template.gitlab-deployment-status: |
       webhook:
         gitlab:
           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: |
       url: https://gitlab.com/api/v4
       headers:
       - 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": {"notifications.argoproj.io/subscribe.on-deployed.gitlab":""}}}' --type merge