# Pull request checks

A pull request's checks are its CI results, as your Git provider reports them. You follow them on
the session page, under each pull request: see why a check failed, run a failed check again, and
let the agent fix the failures its own changes caused.

<Availability permission="Sessions: Read to see checks and why they failed. Sessions: Update to re-run a failed check." />

## Key concepts

**Checks.** The pull request's CI results, as your Git provider reports them. Each check shows how
long it took, for example **Successful in 1m** or **Failing after 15s**, and a check that is still
running counts up every second, for example **Started 45s ago**. Point at the time to see exactly
when the check started and, once it's done, when it finished. On GitLab and Bitbucket the time
includes any wait before the check started. A check that reports only its result shows no time.

Checks update on their own while they run. On GitHub they move as soon as GitHub reports them,
including in the repository of an application started from a template. Otherwise they are read
again every 15 seconds while one is still running.

**Failed jobs.** Every job that failed on a pull request's latest commit is listed in the
session's **Errors** tab, next to the session's other errors, and each failed check links to it with
**View error**. A failed check can be several failed jobs, such as a GitLab pipeline: each job is
listed on its own.

**Deployment jobs.** Once a pull request is merged into a branch one of your
[environments](/user-guide/engineering/environments) deploys, its deployment jobs appear under its
checks, below a thin heading that names the environment, such as **Deployment · Development**. They
are the jobs [Deployments](/user-guide/engineering/deployments) shows for that merge: the jobs of the
deploy run when the application deploys to one of your cloud accounts, otherwise every check that
ran on the merged commit. They move as the jobs move, and until the first one starts the heading
says **Waiting for the deployment's checks to start...**. They are shown only: they don't count
towards the pull request's checks, and a failing deployment job never starts CI auto-fix. A pull
request merged into a branch no environment deploys shows none.

**CI auto-fix.** When a pull request's checks fail, Productmind can send the failures to the agent,
which fixes the ones its own changes caused. The failures it sent are listed in the **Errors** tab
too. Your workspace sets it up in [Templates](/user-guide/engineering/agents/templates).

## When a check fails

### To see why a check failed

Every failed check shows **View error**, beside its **Details** and re-run button.

1. Under the pull request's checks, choose **View error** beside the failed check. Or, in the
   rail, choose **Errors**.

The **Errors** tab opens on the check's failed job, expanded. Each failed job is marked **CI
check** and names its pull request, then shows:

- the step that failed. On GitLab, the reason the job ended, such as **Script failure**;
- on GitHub, the errors your CI located in your code, with the file and the line;
- the end of the job's log, with a copy button. A long log is cut to its last lines, and says so;
- **Open the run**, which opens the check in your CI service.

On GitLab, each failed job of the pipeline is listed. On Bitbucket, the failed steps of the
Bitbucket Pipelines runs for the pull request's latest commit are listed, and every failed check
opens the first of them.

Productmind reads the failures from your Git provider when you open the **Errors** tab. Until then,
the tab counts the failed checks, and once the read is done it counts the failed jobs. Nothing is
stored. A failed job leaves the list once its check passes again, after a re-run or a new commit,
and a new commit's failures replace the previous commit's.

Your Git provider describes the first failures to finish, a few per pull request. A failed check it
didn't describe says its log wasn't read. It usually failed because of the first ones.

A check from another CI service keeps its log in that service: choose **Open the run** to open it
there. If a failure couldn't be read, the reason is shown, for example a permission your Git
connection is missing. When nothing could be read, choose **Try again**.

For an application started from a template, this is where you see why a check failed, because its
check details open on GitHub only for the repository's collaborators.

Your CI hides the secrets you registered with it, but anything else a job prints appears here, to
everyone who can see the session's pull requests.

Where you have no **Errors** tab for the session, such as someone else's code chat, the list of a
pull request's checks ends with **Why it failed** instead. Choose it to read the same failures
under the checks.

### To read a failure the agent was sent

When the agent was sent a failed check, **View error** opens the failure it was sent, listed once
in the **Errors** tab. Or, in the Pull Requests panel, choose the number of failed CI checks under
the pull request.

The failure shows the same parts, and the replies on it, such as the agent saying the failure isn't
caused by its changes.

To stop a failure being sent to the agent again, choose **Resolve**. **Reopen** sends it with the
next **Apply code revisions**.

### To re-run a failed check

When a check fails for a reason that has nothing to do with the change, such as a flaky test or a
runner that went away, you can run it again without leaving Productmind.

1. Next to the failed check, choose the re-run button (the circular arrow, before **Details**).

The button turns into a spinner until your Git provider starts the new run. The check then shows
as running, and its new result replaces the failure when it finishes. If it fails again, the button
comes back.

- On GitHub, it re-runs that job of the workflow, and the jobs that depend on it.
- On GitLab, it retries the failed jobs of the merge request's latest pipeline.

Nothing else on the pull request runs again. On GitHub the button is unavailable while other jobs
of the same workflow are still running, because GitHub re-runs a job only once the whole workflow
has finished. Point at it to see why.

Only checks that GitHub Actions or GitLab CI/CD ran on the pull request's latest commit can be
re-run here. A check from another CI service is re-run in that service: choose **Details** to open
it. Checks of a merged or closed pull request, and Bitbucket checks, can't be re-run from
Productmind.

If the check can't be re-run, the reason appears under it.

## How checks behave

**The agent fixes failing checks.** When a pull request's checks fail, Productmind sends the
failure to the agent, which decides whether its own change caused it and, if so, fixes it. The
failures it sent appear in the **Errors** tab, and the checks area says what was done. A failure stays
unresolved until a push carrying the fix reaches its pull request: if your Git provider refuses the
push, the failure is still there. It tries at most twice per session, and once per
commit. Your workspace can turn this off or change the number of attempts. See
[Templates](/user-guide/engineering/agents/templates).

**Each attempt is a billed build turn.** That includes an attempt where the agent finds the
failures aren't caused by its changes and changes nothing. The checks area says so before an
attempt starts, and the person who started the session, its assignee and the person whose machine
runs it are notified when one does. When every failing check is also failing on the base branch,
no attempt starts for that commit.

**A refused attempt leaves the session in review.** When billing refuses an attempt, the failures
are still posted as review comments and the checks area shows what to do about billing. The
refused attempt isn't counted. Once billing allows it, choose **Apply code revisions** to send the
failures to the agent.

**Failing checks hold the merge.** **Merge** waits while checks are running or failing, and the
checks always belong to the pull request's latest commit. See
[To merge a pull request](/user-guide/sessions/pull-requests#to-merge-a-pull-request).

**A new pull request waits for its checks when your repository runs CI.** Your Git provider
starts a pull request's checks a few seconds after it opens. Productmind asks the provider whether
checks are expected: whether the target branch requires them, or a CI file in the repository (a
GitHub Actions workflow, `.gitlab-ci.yml`, `bitbucket-pipelines.yml`, or another CI service's file)
runs on this pull request. If it does, the checks area says **Waiting for checks to start on the
latest commit...** instead of showing the pull request as ready to merge. If the target branch
requires checks, it keeps waiting for them (**Waiting for the required checks to report on the
latest commit...**). If your repository runs no CI, the pull request is ready to merge straight
away.

## Permissions

| To | You need |
| --- | --- |
| See checks, and why one failed in the **Errors** tab | **Sessions: Read** |
| Re-run a failed check | **Sessions: Update** |
| Send the failures to the agent with **Apply code revisions** | **Sessions: Update** |

## Troubleshooting

### Auto-fix didn't start

The checks area says why, after the checks summary:

- **Auto-fix not started: billing refused the run.** Use the billing action under it (for example
  **Top up**), or ask an Owner or Admin. When it says billing is ready, choose **Apply code
  revisions** to send the failures to the agent.
- **Auto-fix skipped: the same checks are failing on** the base branch. Fix them on the base
  branch and re-run the pull request's checks, or message the agent if you want it to look anyway.
- **Auto-fix paused.** The session used all its attempts. Choose **Apply code revisions** to send
  the failures yourself.
- **Auto-fix is off for this workspace.** See
  [Templates](/user-guide/engineering/agents/templates).
- The session notes **CI auto-fix could not start: cloud sessions are off** and the Productmind
  agent it needs is offline. Your workspace runs sessions only on Productmind agents: start that
  agent, then choose **Apply code revisions**. The attempt wasn't counted. See
  [Settings > Coding sessions](/user-guide/settings/workspace-settings/coding-sessions).

Auto-fix also waits while the agent is working on the session, and makes one attempt per commit.

### A failed check has no re-run button

The check can't be re-run from Productmind. It may come from a CI service other than GitHub Actions
or GitLab CI/CD (choose **Details** to re-run it there), have run on an earlier commit (an older
pipeline of a merge request, for example), or belong to a pull request that is merged or closed.
The button also needs **Sessions: Update**.

### Re-running a check says the GitHub App needs the Actions permission

The Productmind GitHub App installed on your GitHub organization can read your workflow runs but
not re-run them. An owner of the GitHub organization must accept the **Actions: Read & write**
permission: in GitHub, under the organization's settings for installed GitHub Apps, open the
Productmind app and accept the requested permissions. Then re-run the check again.

### Re-running a GitLab pipeline says GitLab refused

Your workspace's GitLab connection needs the **api** scope and at least the **Developer** role on
the project to retry a pipeline. Reconnect GitLab in [Integrations](/user-guide/settings/integrations)
with an account that has them.

### Re-running a check says it isn't available for this repository

The repository belongs to an application started from a template, which Productmind hosts, and
re-running its checks is temporarily unavailable. Contact Productmind.

## Related topics

- [Pull requests and reviews](/user-guide/sessions/pull-requests)
- [Templates](/user-guide/engineering/agents/templates)
- [Working in a session](/user-guide/sessions/working-in-a-session)
- [Integrations](/user-guide/settings/integrations)
