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

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, Octopus, or GitHub Actions, you can integrate by selecting the corresponding tile, as shown below. Read more about using these integrations: Jenkins, Octopus, or GitHub Actions.

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 Custom Deploys

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

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": "[email protected]",
    "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": "[email protected]",
    "author_name": "Michael Scott",
    "author_email": "[email protected]",
    "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."
}

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

AttributeTypeRequiredDescription
serviceStringtrueAn alias of the service you wish to track deploys for. These can be found on the service’s detail page.
descriptionStringtrueThe 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_atString/DatetimetrueThe datetime your deploy took place.
deploy_urlStringfalseThe URL for the authoritative source of truth of your deploy
dedup_idStringfalseThe 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.

See How OpsLevel handles duplicate deploys for more details
environmentStringfalseThe environment for which this deploy took place.
deploy_numberStringfalseThe 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):

AttributeTypeRequiredDescription
emailStringtrue (if no deployer name)The email of the deployer. OpsLevel will automatically associate this email to an OpsLevel user
nameStringtrue (if no deployer email)The name of the deployer.
idStringfalseThe 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):

AttributeTypeRequiredDescription
shaStringfalseThe commit sha related to the deploy
messageStringfalseThe message of the commit relating to the deploy
branchStringfalseThe branch of the commit relating to your deploy
dateString/DatetimefalseThe date the commit relating to your deploy happened
committer_nameStringfalseThe committer name of the commit relating to your deploy
committer_emailStringfalseThe committer email of the commit relating to your deploy
author_nameStringfalseThe author name of the commit relating to your deploy
author_emailStringfalseThe author name of the commit relating to your deploy
authoring_dateString/DatetimefalseThe authoring date of the commit relating to your deploy

How OpsLevel handles duplicate deploys

If the Deploy Integration receives more than one payload with a single dedup_id, OpsLevel will respond with a 202 however we will not create additional deploys after the first deploy event with that dedup_id.

Example Response Payload

{
    "result": "duplicate_deploy",
    "message":"Deploy not created due to existing deploy with identical dedup_id"
}

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 CodeTitleDetailDescription
400Deployed at Errorparam is missing or the value is empty: deployed_atThe 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 [email protected] and we’ll help you get set up.