---
title: "GitHub Actions Matrix Job URL for Parallel Cypress Tests"
description: "A tutorial on how to get a GitHub Actions Matrix Job URL in Cypress tests. This is useful for getting a reference to the specific matrix build job from cypress terminal output."
canonical: "https://currents.dev/posts/github-actions-cypress-job-url"
updated: "2022-12-19"
---

# GitHub Actions Matrix Job URL for Parallel Cypress Tests

Published 2022-12-19 by Andrew Goldis.

Canonical URL: https://currents.dev/posts/github-actions-cypress-job-url

A tutorial on how to get a GitHub Actions Matrix Job URL in Cypress tests. This is useful for getting a reference to the specific matrix build job from cypress terminal output.

---


When running cypress tests in a GitHub Actions matrix mode and exploring the tests results in a cloud orchestration dashboard (like Currents, Sorry Cypress or Cypress Cloud) it can be tricky to identify what specific matrix job a test belongs to.

The problem is particulary annoying when many parallel matrix jobs are involved. The test results are presented without any way to identify the associated matrix job. One option is to iterate through the matrix jobs and find the one that matches the failed test. This is a tedious process, and can be difficult to do when there are many jobs.

Unfortunatelty, GitHub actions doesn't provide matrix job URL or identifier as an environment variable. However, one can use the GitHub API to get the matrix job URL.

After obtaining the matrix job URL, it can be printed to the Cypress terminal output. This is useful for getting a reference to the specific matrix build job from cypress terminal output.

TL;DR See the [example repository](https://github.com/currents-dev/gh-matrix-job-url-example)

## Getting the Matrix Job URL

The matrix job URL can be obtained by using the GitHub [list jobs for a workflow run API](https://docs.github.com/en/rest/actions/workflow-jobs?apiVersion=2022-11-28#list-jobs-for-a-workflow-run). For example:

```sh
curl \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>"\
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/actions/runs/RUN_ID/jobs
```

The required parameters are:

- `OWNER` - the GitHub owner of the repository
- `REPO` - the GitHub repository name
- `RUN_ID` - the GitHub Actions run ID

`OWNER/REPO` can be obtained from the `GITHUB_REPOSITORY` env variable, `RUN_ID`. The output would contain the list of jobs, together with their URLs.

In order to filter the desired job, we need to filter the list of jobs by the job name. The job name is available is in the form `JOB_NAME (CONTAINER)`. For example, for the following configuration file:

```yaml
jobs:
  cypress-tests:
    runs-on: ubuntu-20.04
    strategy:
      fail-fast: false
      matrix:
        # run 3 copies of the current job in parallel
        containers: [1, 2, 3]
```

job names would be `cypress-tests (1)`, `cypress-tests (2)` and `cypress-tests (3)`.

Luckly, there's a ready-to-use [GitHub action](https://github.com/Tiryoh/gha-jobid-action) that can be used to get the matrix job URL.

```yaml
jobs:
  cypress-tests:
    runs-on: ubuntu-20.04
    permissions:
      contents: read
      actions: read
    strategy:
      fail-fast: false
      matrix:
        # run 3 copies of the current job in parallel
        containers: [1, 2, 3]
    steps:
      - name: Checkout
        uses: actions/checkout@v2

      - name: Get Current Job Log URL
        uses: Tiryoh/gha-jobid-action@v0
        id: jobs
        with:
          github_token: ${{ secrets.GH_TOKEN }} # GH token with actions:read permissions
          job_name: cypress-tests (${{ matrix.containers }}) # job name filter
          per_page: 30 # increase if you have many jobs

      - name: Output and Save Current Job Log URL
        run: |
          echo ${{ steps.jobs.outputs.html_url }}
          echo "MATRIX_JOB_URL=${{ steps.jobs.outputs.html_url }}" >> $GITHUB_ENV
```

In the example above, we invoke the action with the following parameters:

- `github_token` - the GitHub token with `actions:read` permissions
- `job_name` - the job name filter
- `per_page` - the number of jobs to return per page. Increase this if you have many jobs

The action `Get Current Job Log URL` will output the matrix job URL to the `html_url` output variable. The action `Output and Save Current Job Log URL` will print the matrix job URL to the terminal output and save it to the `MATRIX_JOB_URL` environment variable for [use in the subsequent steps](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-environment-variable).

## Printing the Matrix Job URL in Cypress tests

When Cypress test are running in `record` mode, the terminal output is automatically uploaded to the connected cloud orchestration dashboard. The output is stored separately for each spec file, so we need to print the Matrix Job URL before executing a spec file.

[`before:spec`](https://docs.cypress.io/api/plugins/before-spec-api) hook of [`setupNodeEvents`](https://docs.cypress.io/guides/references/configuration#setupNodeEvents) cypress configuration is a good place to do this.

```js
setupNodeEvents(on, config) {
  on("before:spec", (spec, details) => {
    console.log(`  GH Job URL: ${process.env.MATRIX_JOB_URL}`);
  });
},
```

The output will look like this:

```sh
  (Run Starting)

  ┌────────────────────────────────────────────────────────────────────────────────────────────────┐
  │ Cypress:        12.1.0                                                                         │
  │ Browser:        Electron 106 (headless)                                                        │
  │ Node Version:   v16.18.1 (/usr/local/bin/node)                                                 │
  │ Specs:          9 found (1000.spec.js, crash.spec.js, fails.spec.js, flaky.spec.js, notests.sp │
  │                 ec.js, orchestration_105.spec.js, orchestration_106.spec.js, retries.spec.js,  │
  │                 skipped.spec.js)                                                               │
  │ Searched:       cypress/integration/*.spec.js                                                  │
  │ Params:         Tag: false, Group: false, Parallel: true                                       │
  │ Run URL:        https://app.currents.dev/run/b502c52cc32c3d96cd91f9b1c0e416a8                  │
  └────────────────────────────────────────────────────────────────────────────────────────────────┘


────────────────────────────────────────────────────────────────────────────────────────────────────

  Running:  fails.spec.js                                                                   (1 of 9)
  GH Job URL: https://github.com/currents-dev/dashboard/actions/runs/3738526471/jobs/6344699219


  Some tests fail
    1) Passing Test A
    2) Failing Test B
```

Here's an example of the output in the [Currents dashboard](https://currents.dev/), attached to the associated spec file:

![Gihub Actions Matrix Job URL in Currents dashboard](/img/posts/gh-actions-job-url/cypress-github-action-job-url@2x.png)


---

## About the author

**Andrew Goldis**, Founder. Andrew Goldis is the founder of Currents. He has spent years building tooling for engineering teams that run large end-to-end suites in CI, and writes about test orchestration, flakiness and keeping pipelines fast as they grow.

LinkedIn: https://www.linkedin.com/in/agoldis/