Skip to main content

Test Source Control deployments

Learn how to test changes in Source Control to ensure they deploy without error.

Test deployments serve as a method to confirm that a pull request can be successfully deployed to Retool. They perform a "dry run" of your changes, ensuring that the modifications can be applied to your Retool instance without encountering errors.

In this guide, we’ll refer to a placeholder Retool organization at https://exampleorg.retool.com. Be sure to substitute this placeholder with the actual URL where your Retool instance is hosted. Additionally, replace RETOOL_TEST_DEPLOY_API_KEY with your access token.

Create an access token​

Complete the following steps to create an access token with permissions for test deployment:

  1. Navigate to Settings > Retool API and click Create new.
  2. Enter a name and description for your new access token.
  3. Select the Read and Test Deploy scopes from the Source Control section.
  4. Click Create token and save the API key.

Using the Test Deploy endpoint​

Use the Test source control changes endpoint in the Retool API to check whether a commit can be successfully deployed. Pass the full commit SHA to the endpoint:

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <RETOOL_TEST_DEPLOY_API_KEY>" \
  -d '{"deploy_params": {"commit_sha": "<COMMIT_SHA>"}}' \
  http://exampleorg.retool.com/api/v2/source_control/test_deploy

Add a CI check​

You can also add a check that runs the test deploy as part of your continuous integration process.

This section includes an example that uses GitHub as the source control provider and Buildkite as the CI/CD provider, although the steps outlined here can be applied to any Git-based hosting service.

Using Github Actions​

Follow GitHub's guide on storing information in variables to configure the RETOOL_TEST_DEPLOY_API_KEY environment variable on GitHub. The following code snippet shows an example of a workflow file

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Test Deploy Commit
        run: |
          COMMIT_SHA="${{ github.event.pull_request.head.sha }}"
          echo "Test deploying commit $COMMIT_SHA on https://exampleorg.retool.com/"
          response=$(curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer ${{ secrets.RETOOL_TEST_DEPLOY_API_KEY }}" -d "{\"deploy_params\": {\"commit_sha\": \"$COMMIT_SHA\"}}" https://exampleorg.retool.com/api/v2/source_control/test_deploy)
          echo "API Response:"
          echo "$response"
          if [[ $(echo $response | jq '.data.success') != "true" ]]; then
            echo "Test deployment failed"
            exit 1
          fi

Using Buildkite​

Follow Buildkite's Managing pipeline secrets guide to set the RETOOL_TEST_DEPLOY_API_KEY environment variable on Buildkite. Add the following command to your pipeline.yml file.

pipeline.yml
steps:
  - command: scripts/run_test_deploy.sh

Buildkite recommends that you avoid directly referencing secrets in your pipeline.yml file. Instead, utilize a script stored in your repository for this purpose:

scripts/run_test_deploy.sh
#!/bin/bash
set -euo pipefail

COMMIT_SHA=$BUILDKITE_COMMIT
echo "Deploying commit SHA $COMMIT_SHA on https://exampleorg.retool.com/settings/api/v2/source_control/test_deploy"
response=$(curl -X POST -H "Content-Type: application/json" -H "Authorization: Bearer $RETOOL_TEST_DEPLOY_API_KEY" -d "{\"deploy_params\": {\"commit_sha\": \"$COMMIT_SHA\"}}" https://exampleorg.retool.com/settings/api/v2/source_control/test_deploy)
echo "API Response:"
echo "$response"
if [[ $(echo $response | jq '.data.success') != "true" ]]; then
  echo "Test deployment failed"
  exit 1
fi