deployments.create

Create a new deployment.

This method only creates records and rejects an existing reference_id. Use deployments.upsert for idempotent create-or-update ingestion, or deployments.update to patch an existing deployment without creating one.

Facts

Arguments

Required arguments

Recommended attribution arguments

For DORA lead-time metrics, DX recommends sending one of these patterns with every production deployment:

• repository and commit_sha together, when a single deployed SHA can anchor attribution.
• merge_commit_shas, when the deployment system already knows the exact merge commits that shipped. repository is not required for this path.

Without commit_sha or merge_commit_shas, DX falls back to deployed_at timestamps, which is less precise. Sending repository without a SHA still attributes undeployed pull requests on the repository default branch. See Attribution paths.

If you send commit_sha or merge_commit_shas, include a valid value. commit_sha must be 7—40 characters. Each SHA in merge_commit_shas must be 7—40 characters. Omit the field if you do not have a value. Do not send an empty string.

If attributing deployments to code via a 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.

Choosing a deployment method

• Use deployments.create when every request represents a new deployment and duplicate identifiers should fail.
• Use deployments.upsert when requests should safely create or patch a deployment.
• Use deployments.update when only existing deployments should be patched.
• Use deployments.delete to permanently remove an API-created deployment.

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": "release-v2.4.0",
    "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: ${{ secrets.DX_DEPLOYMENT_API_TOKEN }}
      DATACLOUD_HOST: ${{ secrets.DX_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=${{ github.repository }}

          # 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

Argo CD

If you deploy with Argo CD, Argo CD Notifications can call deployments.create whenever an Application finishes a successful sync, with no separate CI job. This takes four keys in the argocd-notifications-cm ConfigMap: a webhook service that holds the host and auth header, a template that builds the request body, a trigger that decides when to fire, and a subscription that wires the two together.

Store the API token in argocd-notifications-secret instead of the ConfigMap. Notification services resolve $key references against that secret at send time:

kubectl -n argocd patch secret argocd-notifications-secret --type=merge \
  -p '{"stringData":{"dx-api-key":"xxxx-xxxxxxxxx-xxxx"}}'

Then add the four keys to the ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-notifications-cm
  namespace: argocd
data:
  # Holds the host and auth header. `path` in the template below is appended to
  # this url.
  service.webhook.dx: |
    url: https://yourinstance.getdx.net
    headers:
      - name: Authorization
        value: Bearer $dx-api-key
      - name: Content-Type
        value: application/json

  template.dx-deployment: |
    webhook:
      dx:
        method: POST
        path: /api/deployments.create
        body: |
          {
            "service": {"identifier": "{{ .app.metadata.name }}"},
            "deployed_at": "{{ .app.status.operationState.finishedAt }}",
            "reference_id": "argocd/{{ .app.metadata.uid }}/{{ .app.status.operationState.startedAt }}",
            "repository": "orgname/{{ .app.metadata.name }}",
            "commit_sha": "{{ .app.status.sync.revision }}",
            "source_name": "Argo CD",
            "source_url": "{{ .context.argocdUrl }}/applications/{{ .app.metadata.name }}",
            "metadata": {
              "argocd_application": "{{ .app.metadata.name }}",
              "argocd_cluster": "{{ .app.spec.destination.server }}",
              "argocd_namespace": "{{ .app.spec.destination.namespace }}",
              "argocd_sync_status": "{{ .app.status.sync.status }}",
              "argocd_health_status": "{{ .app.status.health.status }}"
            }
          }

  # Fires only on syncs that actually rolled out. Change the destination check to
  # match your production cluster.
  trigger.on-dx-deployment: |
    - when: app.status.operationState.phase in ['Succeeded'] and app.status.health.status == 'Healthy' and app.spec.destination.server contains 'cluster/prod'
      oncePer: app.status.operationState.startedAt
      send: [dx-deployment]

  subscriptions: |
    - recipients:
        - dx
      triggers:
        - on-dx-deployment

Four things to check when adapting this.

Keep reference_id stable across retries. Argo CD retries a delivery that does not return a 2xx, roughly every few minutes until the Application’s next sync, so the payload has to be idempotent. operationState.startedAt is stable across those retries but new for every sync operation, so retries collapse onto one deployment while a genuine redeploy of the same SHA still counts. Use that same field for the trigger’s oncePer: Argo CD’s dedupe and DX’s have to key on the same value, or one of them lets a duplicate through.

Confirm what sync.revision holds. For a git-backed Application it is the commit SHA, which is what commit_sha expects. For an Application that tracks a Helm chart or OCI artifact it is a chart version, and sending that as commit_sha silently breaks lead time attribution — the deployment still lands, but DX cannot match it to a pull request. In that case pull the SHA from wherever your chart carries it, commonly the image tag in .app.spec.source.helm.values:

{{- $vals := .app.spec.source.helm.values -}}
{{- $sha := "" -}}
{{- if regexMatch `(?s).*tag: '([^']+)'.*` $vals -}}
{{-   $sha = regexReplaceAll `(?s).*tag: '([^']+)'.*` $vals `$1` -}}
{{- end -}}

Guard with regexMatch before calling regexReplaceAll, which returns its input unchanged when the pattern does not match. Without the guard, a values block that does not contain a tag puts the entire multi-line blob into commit_sha and the body stops being valid JSON. When the SHA cannot be resolved, omit commit_sha and repository rather than sending a bad value: the deployment still counts toward deploy frequency, and only lead time attribution is lost.

Choose a service identifier that survives your Application layout. .app.metadata.name is convenient, but if you run one Application per cluster or namespace for the same release, it fragments a single service into several. Prefer a value that names the service itself, and use the same identifier across deployments, incidents, and catalog services.

Scope the trigger to production only. Every cluster the trigger matches reports the same release again and inflates deploy frequency, so keep this cluster set narrower than the one you use for Slack notifications.

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.