Antithesis trigger GitHub Action

This action runs an Antithesis test run as a step in a GitHub Action workflow job.

What is Antithesis?

Antithesis is a continuous reliability platform that autonomously searches for problems in your software within a simulated environment. Every problem we find can be perfectly reproduced, allowing for efficient debugging of even the most complex problems.

Usage

This action takes the following inputs to configure its behavior. You can see an example usage here in our demo project glitch-grid.

Instructions

1. Add your Antithesis credentials to your GitHub repository secrets. The action supports two authentication methods — use one of them:

   • API key (recommended): store your Antithesis API key as a repository secret named ANTITHESIS_API_KEY. The action sends it as Authorization: Bearer <api_key>. Contact support@antithesis.com or your forward-deployed engineer to obtain a key.
   • Basic auth (legacy): store your Antithesis username and password as repository secrets named ANTITHESIS_USERNAME and ANTITHESIS_PASSWORD.

   Navigate to your repository action secrets settings found here to add the secret(s). If both an API key and username/password are provided, the API key takes precedence.

2. Create a limited scope PAT token to enable Antithesis to post back results to GitHub. Navigate to your fine-grained access token settings found here and create a limited scope fine-grained access token with minimal permissions. It is recommended to limit the token to the repository running the workflow and to only grant the token permission to read the repository metadata and to read/write the commit status. For example:

3. Add your token to the repository secrets as you did in step one, and give it the name GH_PAT.

4. Call the Antithesis Trigger Action in your workflow file. Using an API key:

- name: Run Antithesis Tests
  uses: antithesishq/antithesis-trigger-action@v0.5
  with:
    notebook_name: my-test-notebook-name
    tenant: my-tenant-name
    api_key: ${{ secrets.ANTITHESIS_API_KEY }}
    github_token: ${{ secrets.GH_PAT }}
    config_image: myconfigcontainer@digest
    images: mycontainer1@digest;mycontainer2:tag
    description: my-desc
    email_recipients: email1@provider.com;email2@provider.com
    test_name: the-test-name
    additional_parameters: |-
      parameter1_name=parameter1_value
      parameter2_name=parameter2_value

Or using basic auth (legacy):

- name: Run Antithesis Tests
  uses: antithesishq/antithesis-trigger-action@v0.5
  with:
    notebook_name: my-test-notebook-name
    tenant: my-tenant-name
    username: ${{ secrets.ANTITHESIS_USERNAME }}
    password: ${{ secrets.ANTITHESIS_PASSWORD }}
    github_token: ${{ secrets.GH_PAT }}
    config_image: myconfigcontainer@digest
    images: mycontainer1@digest;mycontainer2:tag
    description: my-desc
    email_recipients: email1@provider.com;email2@provider.com
    test_name: the-test-name

Inputs

• notebook_name : the name of your test that will be run (provided by Antithesis)
• tenant : your tenant's name (e.g. If your subdomain is $TENANT_NAME.antithesis.com, your tenant name is $TENANT_NAME)
• api_key : An Antithesis API key. When provided, the action authenticates via Authorization: Bearer <api_key> and the username/password inputs are ignored. You must provide either api_key or both username and password.
• username / password : Your Antithesis username and password, used for basic-auth requests. Required when api_key is not set.
• config_image : The image version that Antithesis will pull from the container registry for the config image. This should be a single image version formatted in the same way as those in the antithesis.images parameter.
• images : The image versions that Antithesis will use to build your test environment. The images are specified as an optional registry, a container name and either a digest (which is recommended) or a tag. A ‘;’ delimited list. Each entry is in this format: [REGISTRY/]NAME[:TAG|@DIGEST].
• description : A string description of your test run. The description will be in the headers of the generated report and of any emails triggered by the test run.
• email_recipients : A semi-colon delimited list of the email addresses for the recipients who will be emailed links to the triage report produced by this test run. If this parameter is not specified, emails will be sent to the default users set up for the test.
• additional_parameters : A newline-seperated list of additional parameters to be sent to the test run.
• test_name: An optional name for the test you are running. When specified, the Git commit's status context will be continuous-testing/antithesis (test_name). Otherwise, the default context is continuous-testing/antithesis. This enables users to run more than one Antithesis test per commit.

FAQs

How can I run multiple tests on the same commit using this GitHub Action?

To run multiple tests from the same commit using this GitHub Action, you can set a unique test_name parameter when calling the action. This will create a unique Git commit status context for every unique test_name specified. The example below shows what this will look like if 2 tests were ran for a commit one called first test and the other called second test.