View all methods

deployments.setPullServices

Associate a pull request in a multi-service (monorepo) repository with specific services.

Note: Existing GitHub requests keep working exactly as before — github_pull_id, or repository + pull_number with no source, still default to GitHub. That said, new integrations should always send source explicitly ("source": "github" included), even for GitHub. Omitting source is only supported going forward as a backward-compatibility path for existing GitHub callers.

Facts

Method	POST https://yourinstance.getdx.net/api/deployments.setPullServices

Arguments

Name	Type	Description
token	Token	Auth token passed as an HTTP header.
source	Text	Which source control connector the pull request belongs to. Recommended for every request, including GitHub. Defaults to github when omitted, kept only for backward compatibility with existing GitHub callers. Required to identify a pull request on any other SCM. Supported values: github, gitlab, ado, bitbucket, bitbucket_server, gerrit.
services	Array<Object>	An array of services that have been changed as part of this merge. The name field is optional. When empty and replace: true is set, all existing service assignments are removed and the pull request reverts to its default state, where it can be attributed to all services.
replace	Boolean	When true, the submitted services list replaces all existing service assignments for this pull request. Any previously assigned services not present in the new list will be removed. Defaults to false, which adds the submitted services without removing any existing assignments.

Identifying the pull request

Provide exactly one of the following ways to identify the pull request. Mixing more than one in the same request returns ambiguous_pull_arguments or ambiguous_commit_sha_arguments.

Name	Type	Description
github_pull_id	Integer	GitHub only. The GitHub pull request ID. Cannot be combined with source (other than github) or repository. Example: 1680723287
repository + pull_number	Text + Integer	The repository and the pull/merge request number. For GitHub, GitLab, and Azure DevOps this is the PR/MR number shown in the UI; for Bitbucket and Bitbucket Data Center it’s the pull request ID; for Gerrit it’s the change number. Example: "repository": "orgname/payments", "pull_number": 234
repository + commit_sha	Text + Text	The repository and the merge commit SHA (7–40 chars) for the pull request.
repository + merge_commit_shas	Text + Array<Text>	The repository and one or more merge commit SHAs (7–40 chars each), to set services on multiple pull requests in one call.

The format of repository depends on the connector:

• GitHub, Bitbucket: organization/workspace prefix, e.g. orgname/payments.
• GitLab: the project name alone, e.g. payments. GitLab has no single org prefix — if more than one project shares that name, use the project’s full namespace path instead, e.g. group/subgroup/payments.
• Azure DevOps: project name prefix instead of organization, e.g. myproject/payments.
• Bitbucket Data Center: project key or project name as the prefix, e.g. PROJ/payments.
• Gerrit: project name only, e.g. services/payments-api.

Usage info

Use this API method before deployments.create for repositories where pull requests can affect multiple services. DX associates deployments to pull requests that have been merged since the previous deployment, so service-level attribution can be wrong unless DX knows which services each pull request changed.

The deployments.setPullServices endpoint pre-associates pull requests with services, ensuring that they are attributed correctly when deployment data is later captured. For example, suppose the following events occur:

10 am - merge PR#1 (changes service_a)
11 am - merge PR#2 (changes service_b)
12 pm - merge PR#3 (changes service_a)
12:01 - deploy service_a

If deployments.setPullServices is used after each merge, PR#1 and PR#3 will associate to the deployment but PR#2 will not be considered deployed. If deployments.setPullServices is not used, all pull requests will be considered deployed.

Example request

This is a typical GitHub request. New integrations should include source explicitly, as shown here:

curl -X POST\
  https://yourinstance.getdx.net/api/deployments.setPullServices\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "source": "github",
    "github_pull_id": 1497468863,
    "services" : [
      {
        "name": "Payments",
        "identifier": "payments-service"
      },
      {
        "identifier": "auth-service"
      }
    ]
  }'

Legacy GitHub requests (still supported)

Requests that omit source entirely continue to work for GitHub — this is for backward compatibility with existing integrations, not recommended for new ones:

curl -X POST\
  https://yourinstance.getdx.net/api/deployments.setPullServices\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "github_pull_id": 1497468863,
    "services" : [
      {
        "name": "Payments",
        "identifier": "payments-service"
      },
      {
        "identifier": "auth-service"
      }
    ]
  }'

Other SCMs

Set source and identify the pull request with repository plus pull_number, commit_sha, or merge_commit_shas:

# GitLab merge request, by MR number (iid)
curl -X POST\
  https://yourinstance.getdx.net/api/deployments.setPullServices\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "source": "gitlab",
    "repository": "payments",
    "pull_number": 42,
    "services": [{"identifier": "payments-service"}]
  }'

# Azure DevOps pull request, by merge commit SHA
curl -X POST\
  https://yourinstance.getdx.net/api/deployments.setPullServices\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "source": "ado",
    "repository": "myproject/payments",
    "commit_sha": "a1b2c3d4e5f60718293a4b5c6d7e8f901234567",
    "services": [{"identifier": "payments-service"}]
  }'

# Gerrit change, by change number
curl -X POST\
  https://yourinstance.getdx.net/api/deployments.setPullServices\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer xxxx-xxxxxxxxx-xxxx" \
  -d '{
    "source": "gerrit",
    "repository": "services/payments-api",
    "pull_number": 31968,
    "services": [{"identifier": "payments-service"}]
  }'

bitbucket and bitbucket_server (Bitbucket Data Center) follow the same shape as above.

GitHub Action

Below is an example of a GitHub Actions workflow that gets the names of the services from the files changed in a pull request.

name: Scan Changed Files in PR

on:
  pull_request:
    types:
      - closed
    branches:
      - 'main'

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 50 # pick an appropriate number
    - name: Get list of changed files
      id: getfile
      run: |
        files=$(git diff --name-only $ $ --)
        echo "Changed files: $files"
        echo "Changed files: $files" >> changed_files.txt

    - name: Identify affected services
      id: services
      run: |
        services=""
        while read -r file; do
          service=$(echo $file | awk -F'/' '{print $1}')
          services="$services $service"
        done < changed_files.txt
        unique_services=$(echo $services | xargs -n1 | sort -u | xargs)
        echo "Affected services: $unique_services"
        echo "::set-output name=affected_services::$unique_services"

    - name: Post affected services
      run: |
        services_json=$(echo "$" | jq -R 'split(" ") | map({identifier: .})')
        json_payload=$(jq -n \
          --arg github_pull_id $ \
          --argjson services "$services_json" \
          '{
             source: "github",
             github_pull_id: $github_pull_id,
             services: $services
           }')

        curl -X POST \
          http://yourinstance.getdx.net/api/deployments.setPullServices \
          -H "Content-Type: application/json" \
          -H "Authorization: Bearer YOUR_BEARER_TOKEN_HERE" \
          -d "$json_payload"

        if [ "$RESPONSE_CODE" -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
required_params_missing	No pull selector (github_pull_id, or repository with pull_number/commit_sha/merge_commit_shas) or services was provided.
invalid_services_param	services was not a valid array of service objects.
ambiguous_pull_arguments	More than one pull selector was provided, e.g. both github_pull_id and pull_number, or repository/pull_number together with github_pull_id.
ambiguous_commit_sha_arguments	Both commit_sha and merge_commit_shas were provided in the same request.
source_invalid	source is not one of the supported values, or conflicts with another argument (e.g. source set to something other than github while github_pull_id is present).
pull_number_invalid	pull_number was not a positive integer.
commit_sha_invalid	commit_sha was not a valid SHA (7+ hex characters).
merge_commit_shas_invalid	merge_commit_shas was not an array of valid SHAs.
merge_commit_shas_blank	merge_commit_shas was an empty array.
repo_not_found	The specified repository could not be found for the given source.
repo_ambiguous	More than one repository matched the repository value for the given source.
pull_request_ambiguous	More than one pull request matched the given commit_sha or merge_commit_shas value.