Tracking Deploys

Learn how to integrate OpsLevel with your CI/CD pipeline and track every service deployment across environments.

OpsLevel is your one-stop shop for understanding the microservices you have running in your architecture. A key component to understanding your microservices is to actually see what code is running in production, and when/how that changes.

With the OpsLevel Deploy Integration, you can integrate directly into your CI/CD pipeline to track every deploy of your services. You can begin sending all of your deploys to OpsLevel even if you have not added all of your services yet - we will help match them to existing services, or suggest adding a new service to OpsLevel. This also makes it easy to keep OpsLevel up-to-date.

The deployment info can be handy to get a quick read on how active the development on a given service is, and can be critically useful when debugging or triaging issues that crop up with your services.

Deploys

Getting started with Deploy Webhooks

To set up a deploy webhook, visit our Integrations tab and select “New Integration”, followed by Deploy. (Note that if you don’t have any integrations, you’ll be shown the new integration page directly.)

Alternatively, if you use Jenkins you can create a Jenkins Integration. You can read more about the Jenkins Integration here.

OpsLevel Deploy Integration

Click “+ Add Integration” on the Deploy integration card and then “Create a Deploy Endpoint”:

Add Deploy Integration

After creating a deploy endpoint, you’ll be redirected to a page that looks like:

Deploy Integration Show

Once you’ve successfully created a deploy endpoint, you can begin tracking deploys.

Tracking Deploys

Tracking deploys in OpsLevel is easy. Just make an HTTP POST request (substituting your Webhook URL in place of xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx):

Here is an example with curl but you can also use our CLI.

POST http://app.opslevel.com/integrations/deploy/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Content-Type: application/json

{
  "dedup_id": "9ae54794-dfc5-4ac8-b1b5-78789f20f3f8",
  "service": "shopping_cart",
  "deployer": {
    "id": "1a9f841f-9a3d-4423-a05a-7e9c31a02b16",
    "email": "mscott@example.com",
    "name": "Michael Scott"
  },
  "deployed_at": "2019-02-01 13:28:33",
  "environment": "Production",
  "description": "Deployed by CI Pipeline: Deploy #234",
  "deploy_url": "https://heroku.deploys.com",
  "deploy_number": "234",
  "commit": {
    "sha": "38d02f1d7aab64678a7ad3eeb2ad2887ce7253f5",
    "message": "Merge branch 'fix-tax-rate' into 'master'",
    "branch": "master",
    "date": "2019-02-01 09:23:43",
    "committer_name": "Michael Scott",
    "committer_email": "mscott@example.com",
    "author_name": "Michael Scott",
    "author_email": "mscott@example.com",
    "authoring_date": "2019-02-01 09:23:43"
  }
}

If your webhook was successful, you will receive a 202 response. The payload of the response will differ depending on whether the service provided in the request matches an existing service in OpsLevel. To view all error responses, refer to the Handling Errors section of this doc.

If the service provided in the payload matches a service that lives in OpsLevel, you will receive the following 202 response:

{
  "result": "ok"
}

If we could not match the service from the payload to a service in OpsLevel, we will record the deploy and create a new suggestion based on the service provided. This makes keeping track of deploys for the services you care about a snap - you just need to point your CI/CD pipelines at us!

In this case, you will still receive a 202 response along with the following payload:

{
  "result": "no_service_found",
  "message": "No service found matching alias 'not_found_alias'. Recording 'not_found_alias' as a suggestion."
}

Schema Details

Here is a full explanation of all the fields in the main json object:

Attribute Type Required Description
service String true An alias of the service you wish to track deploys for. These can be found on the service’s detail page.
description String true The description that will be shown along with other deploy information from the OpsLevel UI.(Usually in the form of a commit or merge message)
deployed_at String/Datetime true The datetime your deploy took place.
deploy_url String false The URL for the authoritative source of truth of your deploy
dedup_id String false The deduplication id for the deploy. If your deploy pipeline creates a unique deploy id or key, set that here for the purpose of deduplication and future status tracking.
environment String false The environment for which this deploy took place.
deploy_number String false The number used to track deploys in your deploy pipeline. If no number is provided, OpsLevel will generate a number based on the sequential order of the deploy

Here is a description of all the fields in the deployer object (required):

Attribute Type Required Description
email String true (if no deployer name) The email of the deployer. OpsLevel will automatically associate this email to an OpsLevel user
name String true (if no deployer email) The name of the deployer.
id String false The ID of the deployer. If your pipeline has unique IDs for each deployer, set that ID here.

Here is a description of all the fields in the commit object (optional):

Attribute Type Required Description
sha String false The commit sha related to the deploy
message String false The message of the commit relating to the deploy
branch String false The branch of the commit relating to your deploy
date String/Datetime false The date the commit relating to your deploy happened
committer_name String false The committer name of the commit relating to your deploy
committer_email String false The committer email of the commit relating to your deploy
author_name String false The author name of the commit relating to your deploy
author_email String false The author name of the commit relating to your deploy
authoring_date String/Datetime false The authoring date of the commit relating to your deploy

Handling Errors

Deploy webhooks may throw errors when receiving malformed requests, when utilizing webhook URLs that are no longer valid, or when our team of highly trained chipmunks stop working around the clock to make your webhooks get through to us.

In such cases, deploy webhooks return verbose and descriptive errors.

An example of such error:

{
  "errors": [
    {
      "status": 400,
      "title": "Description Error",
      "detail": "param is missing or the value is empty: description"
    }
  ]
}

The error above notifies the user that even though we received the webhook payload, the service provided was not found in your OpsLevel account.

Common Errors

Error Code Title Detail Description
400 Deployed at Error param is missing or the value is empty: deployed_at The payload provided is missing one of the required fields. Please see above.

If you are having trouble setting up your deploy pipeline in any way, send us an email at support@opslevel.com and we’ll help you get set up.