Skip to main content
All CollectionsAPI and Continuous Integration (CI)
Continuous integration with Github Actions
Continuous integration with Github Actions
G
Written by Georgij Lazarevski
Updated over a month ago

Usetrace allows you to run traces from your GitHub Workflows using our Usetrace Github Action, helping to catch issues early in your development process. This doc will guide you through setting up and using the action in your projects.

Prerequisites

Setting up your workflow

1. In your repository on GitHub.com, create a workflow file called for example github-usetrace-integration.yml in the .github/workflows directory. Here is how you can do it from GitHub UI:

  • If the .github/workflows directory already exists on your repository, navigate to that directory on GitHub and then:
    ​Click Add file
    ↳Click Create new file
    ↳Name the file github-usetrace-integration.yml.
    ​

  • If your repository doesn't have a .github/workflows directory, go to the main page of the repository on GitHub:

    Click Add file
    ↳Click Create new file
    ↳Name the file .github/workflows/github-usetrace-integration.yml
    ​
    This creates the .github and workflows directories and the github-usetrace-integration.yml file in a single step.

GitHub will automatically evaluate any yml or yaml file it discovers in the .github/workflows directory. You can give the workflow file any name you like.
​
2. Copy the following YAML contents into the github-usetrace-integration.yml file:
​

name: Invoke a Trace on Usetrace on push to development branch
on:
  push:
    branches:
      - development

jobs:
  test-usetrace-action:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
    - name: Run Usetrace Trace and Wait for it to finish
      id: executeTrace
      uses: usetrace/github-action@v1
      with:
        # Required parameters
        trigger-type: project # Options: 'trace' or 'project'
        # Replace the placeholder of the following line with your ID
        trigger-id: {Trace Id/Project Id} # Id of a test Project or Trace
        
    - name: Check Trace execution result
      env:
        RESULT_REPORT: ${{ steps.executeTrace.outputs.report }}
      run: |
        echo "REPORT: $RESULT_REPORT"

3. The action requires two inputs:

  • trigger-type: Either 'trace' (for a single trace) or 'project' (for multiple traces).

  • trigger-id: The ID of your Usetrace trace or project.

Replace the {Trace Id/Project Id} in the yml with the Id of your Trace or Project. It's recommended to store the trigger-id as a variable in your GitHub repository settings.
​

How to find the Id of your Trace

You can find it by selecting the project that contains the Trace you want to trigger in your Usetrace account and then:
​Click All Traces in the top navigation bar
↳ Click on the Trace you want to trigger to open it
↳ Copy the last part of the URL of your browser
​
You will have a URL like this: https://team.usetrace.com/editor/#trace/ZoMvAy6weAAXXcb3jfGGG9QPEvnsqTNY and you need to copy the last part. In this case: ZoMvAy6weAAXXcb3jfGGG9QPEvnsqTNY
​

How to find the Id of your Project

You can find it by selecting the project in your Usetrace and then:
Click Preferences in the top navigation bar
↳ Click on Project in the left menu
↳ Scroll down and you will find the field Project ID
​
It will look something like this: ZodMfx6ReAAXXca7VhlygnfF8lGO5Pok
​

4. Now once any change is pushed into the development branch, the workflow will run, it will trigger the Trace/Project you configured and wait for it to finish.

Optional Inputs

General Arguments

  • browsers: Comma-separated list of browsers (e.g., 'chrome, firefox') If none is specified then tests will run in Chrome.

  • base-url: Base URL to execute against (defaults to the project base URL).

  • parameters: Object trace parameters. You can pass them as JSON attributes. Ex: '"key1": "value1", "key2": "value2"',.

  • usetrace-api-key: Usetrace API Key for authentication.

  • build-timeout-seconds: Maximum time to wait for the build before timing out the workflow. Default: 3600 seconds (60 minutes).

Workflow Control

  • fail-on-failed-traces: Determines whether the workflow should fail if any traces fail. Set to 'true' to fail the workflow if the count of failed traces is not zero, and to 'false' to always pass the workflow regardless of trace results. Default: 'true'.

Reporter Webhook

You can tell Usetrace to notify when the build finishes using the Reporter Webhook and personalize its behavior.

  • webhook-url: URL of the POST callback to send the result. You must include this value if you want a webhook to be invoked when the build finishes.

  • webhook-when: Designation of when the webhook should be triggered. Available values: 'always', 'fails' (on failures only), 'changes' (on result changes only). Default: 'always'.

  • webhook-secretkey: If provided, a HMAC signature will be created and passed via a Signature header to verify the validity of the POST response payload.

  • webhook-username: Username for basic auth if the callback URL is behind an auth wall.

  • webhook-password: Password for basic auth.

Project-Only Arguments

These arguments only work if you are triggering with trigger-type: project :

  • tags: Comma-separated list of tags. Only traces with those tags will be run (by default run all Traces).

  • commit: Hash of the commit leading to this build.

  • commit-link: Link to the commit.

Please take a look at the official Usetrace documentation for more detailed information on creating and managing your tests.

Here are some more resources you should check:

Did this answer your question?