deployments.create

Create a new deployment.

Facts


Method	`POST https://yourinstance.getdx.net/api/deployments.create`

Arguments

Required arguments

Name	Type	Description
`token`	`Token`	Auth token passed as an HTTP header.
`deployed_at`	`ISO-8601`	Timestamp of the deployment. Example: `2025-01-01T12:05:00`
`service`	`Text`	The name of the service that the code was deployed to. Example: `payments-service`

If attributing deployments to code via single commit SHA:

Name	Type	Description
`repository`	`Text`	Repository name associated with the deployment—including the organization prefix. Example: `myorg/payments` For Bitbucket Cloud, include only the repo name. For Bitbucket Data Center, include the project key as a prefix, project_key/repository_name *For ADO, prefix repo name with the project name instead of organization.
`commit_sha`	`Text`	Commit SHA deployed to production. Length must be between 7—40 chars. If SHA is not provided, deployment attribution will be done by deployed_at timestamps which is less accurate. Example: `a0e61dfff93b2b07788cacf2c1cb3948ed4a39b2`

If attributing deployments to specific set of commit SHAs:

Name	Type	Description
`merge_commit_shas`	`Array<Text>`	An array of commit SHA strings being deployed, used for attributing deploys to pull requests. Each commit SHA should be 7—40 chars. Example: `["a0e61dfff93b", "07788cacf2c"]`

Optional arguments

Name	Type	Description
`reference_id`	`Text`	Unique identifier for the deployment. If not provided, a random UUID is generated by DX. DX returns a 409 error if a subsequent request for the same reference_id changes the values. Example: `1680723287`
`source_url`	`Text`	An external URL containing more information about your deployment. This will be displayed in the UI when exploring your data. Example: `https://my_argocd.myplace.org/build/1791`
`source_name`	`Text`	The source for the deployment to help you differentiate and compare data generated from different types of deploy systems. Example: `argoCD`
`metadata`	`JSON`	You may pass a metadata object with additional data about your deployment that you define. Example: `{ "version": "v1.11.23" }`
`integration_branch`	`String`	Set this value if you are using a branch to integrate changes before merging to a release branch. Example: `develop`
`success`	`Boolean`	Whether the deployment was successful. Example: `true`
`environment`	`Text`	If not specified, deployments default to “production”. Example: `{ "prod": "production": "staging": "dev": "preprod"}`

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, whereas deploy rules are a no-code solution for simple workflows.

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.

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:00",
    "service": "my_service",
    "commit_sha": "d1a34f0",
    "repository": "my_org/payment_api"
  }'

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="My service"
          json_payload=$(jq -n \
                  --arg service "$service" \
                  --arg repo "$repo" \
                  --arg sha "$sha" \
                  --arg ts "$ts" \
                  '{
                    service: $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.

Error	Description
`not_authed`	This error occurs if the API request does not include a valid API key for authentication.
`invalid_auth`	The provided API key is invalid. This can happen if the key is expired or does not exist.
`account_inactive`	The user account associated with the API key is deactivated or suspended.
`invalid_json`	The JSON body of the request could not be parsed. This usually indicates a syntax error.
`required_params_missing`	One or more required parameters were not provided in the request.
`repo_not_found`	The specified repository could not be found. This could be due to a typo or an incorrect repository name.