Deployments

You need to authenticate using your API key in order to track your deployments.

Create Deployment

Request

Endpoint: /deployments/

Method: POST

Headers:

content-type: application/json

Body (optional):

{
  "repository_full_path": "my-org/my-repo-name",
  "status": "success",
  "deployed_at": "2023-07-24 10:30:00"
}

Note

• The API endpoint does not require any request body. It can be accessed with an empty body.

• If the repository_full_path parameter is supplied in the request body, the deployment will be associated with the specified repository on SourceLevel's side. This allows the metrics to be linked to the provided repository.

• The status parameter is optional and can be used to specify the deployment status as success or broken. If not supplied, the API will assume the status as success.

• The deployed_at parameter is optional and can be used to specify the deployment time in the format "YYYY-MM-DD HH:mm:ss". If not supplied, the API will consider the request sent time as the deployment time.

Response

The API responds with the created deployment details.

• Status Code: 201 Created

  Description: The request was successful, and the deployment was created. The response body will be empty.

• Status Code: 422 Unprocessable Entity

  Description: The request body includes invalid data, and the deployment could not be created.

  Response Body:

  {
    "message": "Failed to register deployment, please try again."
  }
  

Examples

Using default values

Creating a deployment assuming success and the current time as the deployment time:

curl --request POST \
  --url https://api.sourcelevel.io/deployments/ \
  --header 'Authorization: Bearer 9c934aecd3d5246dc2ad2d6646b82cac330e94c57d7a9e633323d9f87aeb23c5' \
  --header 'content-type: application/json'

Including details

Creating a deployment with specified status:

curl --request POST \
  --url https://api.sourcelevel.io/deployments/ \
  --header 'Authorization: Bearer 9c934aecd3d5246dc2ad2d6646b82cac330e94c57d7a9e633323d9f87aeb23c5' \
  --header 'content-type: application/json' \
  --data '{
  "repository_full_path": "my-org/my-repo-name",
  "status": "broken"
}'

The status can be either success or broken.

Note that using the broken status does not imply a failed deployment process. Instead, it indicates that the deployment was successfully executed, but it caused unavailability of any services related to the changes included in the deployment, based on DORA metrics.

Registering past deployments

Creating a deployment with specified status and deployment time:

curl --request POST \
  --url https://api.sourcelevel.io/deployments/ \
  --header 'Authorization: Bearer 9c934aecd3d5246dc2ad2d6646b82cac330e94c57d7a9e633323d9f87aeb23c5' \
  --header 'content-type: application/json' \
  --data '{
  "repository_full_path": "my-org/my-repo-name",
  "status": "broken",
  "deployed_at": "2023-07-24 10:30:00"
}'

Ruby: Capistrano

In your Capistrano deploy.rb file, you can add the following code to track deployments using curl.

namespace :deploy do
  desc 'Track deployment using SourceLevel API'
  task :track_deployment do
    api_key = 'YOUR_API_KEY'
    repository_full_path = 'your-org/your-repo'
    status = 'success'
    deployed_at = Time.now.strftime('%Y-%m-%d %H:%M:%S')

    # Execute the curl command to track deployment
    `curl --request POST \
      --url https://api.sourcelevel.io/deployments/ \
      --header 'Authorization: Bearer #{api_key}' \
      --header 'content-type: application/json' \
      --data '{
        "repository_full_path": "#{repository_full_path}",
        "status": "#{status}",
        "deployed_at": "#{deployed_at}"
      }'`
  end

  after :finished, 'deploy:track_deployment'
end

Python: Fabric

In your Fabric fabfile.py, you can add the following code to track deployments using the requests library:

from fabric.api import local, task
import requests
import json

@task
def deploy():
    api_url = 'https://api.sourcelevel.io/deployments/'
    api_key = 'YOUR_API_KEY'
    repository_full_path = 'your-org/your-repo'
    status = 'success'
    deployed_at = '2023-07-24 10:30:00'

    data = {
        "repository_full_path": repository_full_path,
        "status": status,
        "deployed_at": deployed_at
    }

    headers = {
        'Authorization': f'Bearer {api_key}',
        'content-type': 'application/json'
    }

    # Use the requests library to make a POST request
    response = requests.post(api_url, data=json.dumps(data), headers=headers)

    if response.status_code == 201:
        print('Deployment tracking successful!')
    else:
        print(f'Failed to track deployment. Error: {response.text}')

Ansible

In your Ansible playbook, you can add the following code to track deployments using the uri module:

- name: Track deployment using SourceLevel API
  hosts: localhost
  gather_facts: no
  vars:
    api_url: 'https://api.sourcelevel.io/deployments/'
    api_key: 'YOUR_API_KEY'
    repository_full_path: 'your-org/your-repo'
    status: 'success'
    deployed_at: '{{ ansible_date_time.iso8601 }}'
  tasks:
    - name: Track deployment
      uri:
        url: '{{ api_url }}'
        method: POST
        headers:
          Authorization: 'Bearer {{ api_key }}'
          Content-Type: 'application/json'
        body_format: json
        body:
          repository_full_path: '{{ repository_full_path }}'
          status: '{{ status }}'
          deployed_at: '{{ deployed_at }}'
      register: result

    - debug:
        msg: 'Deployment tracking successful!'
      when: result.status == 201
    - debug:
        msg: 'Failed to track deployment. Error: {{ result.json.message }}'
      when: result.status == 422

Please note that you need to install the requests library for Python and have the appropriate API key for these examples to work. Similarly, ensure you have the necessary modules and libraries installed for each tool to run these code snippets successfully.