deployments.create

Create a new deployment.

Facts

Arguments

Required arguments

If attributing deployments to code via single commit SHA:

If attributing deployments to specific set of commit SHAs:

Optional arguments

Usage info

Deployments API methods allow creating deployments in DX from any data source. API-created deployments offer a flexible approach that can handle a wide range of deployment mechanisms.

For DORA metrics, the API-required fields are not always enough. DX also needs enough attribution data to know which production deployment shipped which pull requests or commits, and which service was deployed.

In most workflows, call deployments.create when a CI/CD pipeline completes a production deployment. If deployment events are aggregated or stored elsewhere, you can batch API calls and submit deployment data to DX on a regular schedule.

DORA attribution fields

Use these fields when the deployment should contribute to DORA reporting:

If you send success, omit it for successful deployments or send a JSON boolean such as true or false. Do not send string values such as "true".

For monorepos where a pull request can affect multiple services, use deployments.setPullServices with this method so DX can attribute pull requests to the right service deployments.

Attribution paths

DX supports several paths to attributing deployments to code changes:

• When only the repository argument is provided, the deployment is attributed to all non-deployed pull requests in the specified repository with base refs equal to the default branch of the repository.

• When the commit_sha and repository arguments are provided, the deployment is attributed to the matching pull request as well as all previous non-deployed pull requests with the same repository and base ref as the matching pull request.

• When the commit_sha, repository, and integration_branch arguments are provided, the deployment is attributed only to pull requests merged into the integration_branch. The time range used to identify pull requests comes from the pull request matching the SHA, and the one from the previous deployment.

• When the merge_commit_shas argument is provided, the deployment is attributed to the specific pull requests that correspond to the provided SHAs.

For scenarios 2 and 3 described above, “previous deployment” is defined as the most recent deployment using deployed_at that has the same environment, repository, and service as the deployment sent in. DX attributes deployments to historical pull requests to fill in presumed gaps. For example, if given the commits and deployments shown below, commits A and B are attributed to Deployment 1, and commits C, D, and E are attributed to Deployment 2.

Commit    Deployment Id     Deploy Timestamp
------    -------------     ----------------
A
B         1                 2024-03-01
C
D
E         2                 2024-06-01

Attribution is attempted immediately. Since there is no guarantee that the related repository data has been imported yet, attribution will be retried until relevant data is found for up to three days.

Backfilling historical deployments

You can backfill historical deployments by providing a CSV sheet containing the same fields as used for the deployments.create endpoint. Each row in the spreadsheet represents one deployment. Once you the CSV ready, contact your DX account representative to get your CSV imported.

Example request

This is a typical request:

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
   --data '{
    "reference_id": "globally-unique-identifier",
    "deployed_at": "2025-01-01T12:05:00Z",
    "service": {
      "name": "Payments",
      "identifier": "payments-service"
    },
    "commit_sha": "d1a34f0",
    "repository": "my_org/payment_api"
  }'

Deployment examples by workflow

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "repository": "orgname/repository",
    "service": {"identifier": "my_service"},
    "commit_sha": "abc1234",
    "deployed_at": "2025-01-01T12:05:00Z"
  }'

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "repository": "orgname/repository",
    "service": {"identifier": "my_service"},
    "commit_sha": "abc1234",
    "deployed_at": "2025-01-01T12:05:00Z",
    "integration_branch": "develop"
  }'

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "repository": "orgname/repository",
    "service": {"identifier": "my_service"},
    "commit_sha": "abc1234",
    "deployed_at": "2025-01-01T12:05:00Z",
    "metadata": {
      "commit_timestamp": 1699999999
    }
  }'

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "repository": "orgname/repository",
    "service": {"identifier": "my_service"},
    "commit_sha": "abc1234",
    "deployed_at": "2025-01-01T12:05:00Z",
    "metadata": {
      "first_commit_timestamp": 1699999999
    }
  }'

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "repository": "orgname/repository",
    "service": {"identifier": "my_service"},
    "deployed_at": "2025-01-01T12:05:00Z",
    "merge_commit_shas": ["abc1234", "abc2345"]
  }'

curl -X POST https://yourinstance.getdx.net/api/deployments.setPullServices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_bearer_token_here" \
  -d '{
    "github_pull_id": 1497468863,
    "services": [{"name": "Service A", "identifier": "serviceA"}, {"name": "Another Service", "identifier": "other-service"}]
  }'

curl -X POST https://yourinstance.getdx.net/api/deployments.create \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "repository": "orgname/repository",
    "service": {"identifier": "my_service"},
    "deployed_at": "2025-01-01T12:05:00Z"
  }'

GitHub Action

Below is an example of a GitHub Actions workflow that registers deployments after pull requests are merged.

name: Register deploy in DX Data Cloud
on:
  pull_request:
    types:
      - closed
jobs:
  register_deploy:
    runs-on: ubuntu-latest
    env:
      API_TOKEN: $
      DATACLOUD_HOST: $
    steps:
      - name: Register deploy
        if: github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main' # Change 'main' to your base branch name
        run: |
          sha=$(git rev-parse HEAD)
          ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
          repo=$

          # This is optional - drop from curl if not used
          service="payments-service"
          json_payload=$(jq -n \
                  --arg service "$service" \
                  --arg repo "$repo" \
                  --arg sha "$sha" \
                  --arg ts "$ts" \
                  '{
                    service: {identifier: $service},
                    repository: $repo,
                    commit_sha: $sha,
                    deployed_at: $ts
                  }')
          RESPONSE_CODE=$(curl \
            "https://${DATACLOUD_HOST}/api/deployments.create"\
            -s -o response.txt\
            -w "%{http_code}" -X POST \
            -H "Authorization: Bearer ${API_TOKEN}" \
            -H "Content-Type: application/json"       \
            -d "$json_payload"
          )

        if [ "$RESPONSE" -ne 200 ]; then
          ERROR_MESSAGE=$(jq -r '.message' response.txt)
          ERROR_TYPE=$(jq -r '.error' response.txt)

          echo "Error response from API: HTTP status code $RESPONSE"
          echo "Error type: $ERROR_TYPE"
          echo "Error message: $ERROR_MESSAGE"

          exit 1 # Fail the step explicitly if an error is detected
        fi

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.