Custom Deploys

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.

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

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

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:

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

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

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

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.