Synthetics and CI GitHub Actions

Synthetics and CI GitHub Actions

Overview

Trigger Synthetic tests from your GitHub workflows with the Datadog CI Synthetics command.

Setup

To get started:

  1. Add your Datadog API and Application Keys as secrets to your GitHub repository. For more information, see API and Application Keys.
  2. In your GitHub workflow, use DataDog/synthetics-ci-github-action.

Your workflow can be simple or complex.

Simple workflows

Example workflow using public IDs

name: Run Synthetics tests using the test public IDs
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run Datadog Synthetics tests
        uses: DataDog/synthetics-ci-github-action@v0.2.1
        with:
          api_key: ${{secrets.DD_API_KEY}}
          app_key: ${{secrets.DD_APP_KEY}}
          public_ids: 'abc-d3f-ghi, jkl-mn0-pqr'

Example workflow using an existing synthetics.json file

name: Run Synthetics tests using an existing synthetics.json file
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run Datadog Synthetics tests
        uses: DataDog/synthetics-ci-github-action@v0.2.1
        with:
          api_key: ${{secrets.DD_API_KEY}}
          app_key: ${{secrets.DD_APP_KEY}}

Note: By default, this workflow runs all the tests listed in {,!(node_modules)/**/}*.synthetics.json files (every file ending with .synthetics.json except for those in the node_modules folder). You can also trigger a list of Synthetics tests by specifying a public_id or using a search query.

Complex workflows

Example workflow using the test_search_query

name: Run Synthetics tests by test tag
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run Datadog Synthetics tests
        uses: DataDog/synthetics-ci-github-action@v0.2.1
        with:
          api_key: ${{secrets.DD_API_KEY}}
          app_key: ${{secrets.DD_APP_KEY}}
          test_search_query: 'tag:e2e-tests'

Example workflow using a global configuration override with config_path

name: Run Synthetics tests with custom config
jobs:
  e2e_testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run Datadog Synthetics tests
        uses: DataDog/synthetics-ci-github-action@v0.2.1
        with:
          api_key: ${{secrets.DD_API_KEY}}
          app_key: ${{secrets.DD_APP_KEY}}
          config_path: './synthetics-config.json'

Inputs

Name Type Requirement Description
api_key string required Your Datadog API key. This key is created by your Datadog organization and should be stored as a secret. Default: none.
app_key string required Your Datadog Application key. This key is created by your Datadog organization and should be stored as a secret. Default: none.
public_ids string optional String of public IDs separated by commas for Synthetic tests you want to trigger. If no value is provided, the action looks for files named with synthetics.json. Default: none.
test_search_query string optional Trigger tests corresponding to a search query. Default: none.
subdomain string optional The name of the custom subdomain set to access your Datadog application. If the URL used to access Datadog is myorg.datadoghq.com, the subdomain value needs to be set to myorg. Default: app.
files string optional Glob pattern to detect Synthetic tests config files. Default: {,!(node_modules)/**/}*.synthetics.json.
datadog_site string optional The Datadog site. For users in the EU, set to datadoghq.eu. For example: datadoghq.com or datadoghq.eu. Default: datadoghq.com.
config_path string optional The global JSON configuration is used when launching tests. See the example configuration for more details. Default: datadog-ci.json.

Further Reading

Additional helpful documentation, links, and articles:

Development


yarn jest

# Build project
yarn build

# Compile project and its dependencies for release
yarn package

Release Process

Releasing a new version of synthetics-ci-github-action unfolds as follow:

  1. Create a new branch for the version upgrade.

  2. Update the version using yarn version [--patch|--minor|--major] depending on the nature of the changes introduced. You may refer to Semantic Versioning to determine which to increment.

  3. Push the branch along with the release tag (git push --tags) to the upstream (Github). Create a Pull Request with the changes introduced detailed in the description and get at least one approval.

  4. Merge the Pull Request.

  5. Create a Github Release from the Tags page with the description of changes introduced.

    ⚠️ Ensure the release version follows the expected format vX.X.X.

Once the release has been created, the new version of the Github Action is available to use as a workflow.