> ## Documentation Index
> Fetch the complete documentation index at: https://empirical.run/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Linked Test Changes

> Block an app pull request until its test changes are merged

When a feature changes the UI, its test changes live on a test-repository branch with the same
name as the application branch (see [Branching](https://empirical.run/docs/features/branching.md)). If the application pull
request merges first, runs on your default branch use tests that don't know about the feature yet,
and they fail.

The linked test changes reporter (`github_linked_changes`) tracks that test branch for the
application pull request a run was triggered for, and keeps a check named
`Empirical linked test changes` on the pull request up to date. The check fails while the test
branch has commits that are not merged into the test repository's default branch, and passes once
there is nothing left to merge.

## Results

| Test branch | Check | Title |
| - | - | - |
| No branch with the pull request's head branch name | Pass | No unmerged linked changes |
| Branch exists, nothing to merge (or already merged and deleted) | Pass | No unmerged linked changes |
| Branch is ahead of the default branch, no open test PR | Fail | No test PR for linked test changes — open and merge one first |
| Test PR is open | Fail | Test PR #N open — merge with app PR |
| Test PR is open with merge conflicts | Fail | Test PR #N has conflicts — resolve and merge it before this PR |
| GitHub could not be reached | Fail | Could not check linked test changes |

The check links to the latest test run for the pull request.

## When it updates

The check is written on the pull request's current head commit:

* when a test run is triggered for the pull request, so every new commit that triggers a run gets
  a check, including pull requests without any test changes
* when the test branch changes: a push, a test PR opened, closed or merged, or the branch deleted

## Set up

1. Install the [GitHub Reporter](https://empirical.run/docs/integrations/github.md) on your application repository, with
   access to checks.
2. Trigger runs for pull requests with `trigger.event: "pull_request"` and a `build` with the
   repository and commit. The [dispatch-action](https://empirical.run/docs/triggers/ci-cd.md#github-actions) does both on
   `pull_request` workflow events; for API calls see
   [Pull request runs](https://empirical.run/docs/triggers/ci-cd.md#pull-request-runs).
3. Keep `github_linked_changes` in the environment's reporters. Installing the GitHub Reporter
   turns it on for your environments, with the other GitHub reporters. Turn it off under
   **Settings → Environments**, or leave it out of the `reporters` of a
   [trigger request](https://empirical.run/docs/platform/test-run-configuration.md#choosing-reporters-for-a-run).

A run with `github_linked_changes` asks Empirical to track its pull request's test branch. The
pull request's latest run decides: if that run does not have the reporter, the check stops
updating. Runs not triggered by a pull request have no test branch to track, and the reporter does
nothing for them.

## Making it a required check

Every pull request that triggers a test run gets the check, and it passes when there are no test
changes, so you can require it in your branch protection rules or rulesets.

> [!WARNING]
>
> A pull request that never triggers a test run, for example because your workflow skips it with a
> `paths` filter, gets no check. A required check then waits forever. Require the check only if
> every pull request to the protected branch triggers a run.

## Merging test PRs

Merge test PRs with a merge commit, as the Empirical dashboard and agents do. After a squash or
rebase merge in GitHub, the test branch still looks unmerged and the check keeps failing. Delete
the test branch after such a merge to pass the check.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.