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

# Fix GitHub CI

> Use OpenSRE to inspect failing GitHub Actions checks on a pull request or branch, apply a fix, and push a repair branch.

## Overview

OpenSRE can inspect failing GitHub Actions checks on a pull request or named branch, apply a code fix, commit it, push it, and wait for the new checks.

It can also fix failing CI on a branch with no PR — say "fix the CI on main" and OpenSRE inspects the failing workflow runs on that branch's head commit, applies a fix in a linked worktree, and pushes a fresh repair branch. Say "fix the CI on main and push straight to main" to push the fix onto the branch itself instead.

> [!WARNING]
>
> This is mutating: OpenSRE checks out the branch, edits files, commits, and pushes. At the default autonomy level (`/auto high`) those steps run without prompts; set `/auto med` to be asked before each mutating step. See [Trust mode and `/auto`](https://opensre.com/docs/getting-started/interactive-shell-commands#trust-mode-auto-and-confirmations).

## Prerequisites

* Git installed on the machine running OpenSRE
* `gh` on `PATH` for checks and logs
* GitHub connected in the OpenSRE app with repository write access and workflow/check read access
* Nothing extra for the fix itself: OpenSRE uses an installed coding-agent CLI (Pi, Claude Code, Codex, or Cursor) when one is logged in, and otherwise its built-in coding agent on the LLM you already configured

## Setup

There is no dedicated `integrations setup` target for this tool. Connect GitHub in the OpenSRE app with repository write and workflow/check read access. A named repository or PR URL uses an isolated checkout; an explicitly selected local checkout uses a linked worktree so your branch and uncommitted changes remain untouched.
For requests about your current checkout, you can set the coding workspace:

```bash theme={null}
export CODING_WORKSPACE=/path/to/repo  # optional, for current-checkout requests
# optional:
# export CODING_AGENT=auto   # pi | claude-code | codex | cursor | opensre
# export CODING_MODEL=...
```

With `CODING_AGENT=auto` (the default) OpenSRE picks the first ready CLI and falls back to its built-in agent (`opensre`). The built-in agent reads, searches, and edits files and runs commands (tests, linters, builds) only inside the repair checkout, with `CI=true` and without your OpenSRE or provider secrets in its environment, and never commits or pushes itself. `CODING_MODEL` applies to CLIs only; the built-in agent uses your configured LLM.

## Credentials

| Need | Access |
| - | - |
| Read failing checks / logs | Workflow and check read via token + `gh` |
| Push code fix | Contents write on the same repository |
| Apply the fix | A logged-in coding agent CLI when auto-detected, else the built-in agent on your configured LLM |

## Tools

| Tool | What it does |
| - | - |
| `fix_github_pr_ci` | Inspect failing Actions checks, apply a fix, commit, and push to the existing PR head branch or a fresh branch repair worktree |

Related skill: `repair-github-ci`.

Run `/demo` in the interactive shell for the guided CI/CD onboarding menu; its
recommended first option is CI/CD analytics.

### Use it

In the interactive shell:

```text theme={null}
fix CI on https://github.com/Tracer-Cloud/opensre/pull/4597 and push
fix failing checks on Tracer-Cloud/opensre#4597
fix CI on main in Tracer-Cloud/opensre and push
the current PR CI is failing, fix and push
fix the CI on main
fix the CI on main in Tracer-Cloud/opensre-webapp and push straight to main
```

### What happens

1. OpenSRE reads PR metadata or the latest failing Actions run on the target branch.
2. It fetches compact log excerpts for failing Actions jobs.
3. It creates an isolated checkout for a named repository, or verifies that your explicitly selected checkout matches and uses a linked worktree for branch repairs.
4. It refuses fork PRs because it only pushes to branches in the same repository.
5. After approval, it checks out the PR head branch or creates a fresh repair branch for a branch target such as `main`; a selected local checkout uses a temporary linked worktree.
6. If the PR branch is behind its base branch (whether or not GitHub already reports a conflict), it merges the base branch into the PR branch first, so the fix is made on top of the current base and a failure already fixed there needs no further change. Conflicts go to the coding agent, lockfiles are regenerated rather than hand-merged, and the merge is committed only when no conflict remains.
7. If files changed, it commits only the fix-run changes and pushes the PR branch or fresh repair branch.
8. It verifies the exact pushed commit, allows one minute for its checks to register,
   waits for applicable workflows, and reports whether they passed, failed, were
   superseded by another push, or did not finish within 15 minutes. If GitHub
   reports the pushed commit as conflicted (the base moved during the repair),
   it merges the base branch into the pushed branch once, pushes again, and
   verifies that commit instead.

If no checks are failing, OpenSRE says so and does not push. The one exception is a PR that conflicts with its base branch: GitHub never starts checks for it, so OpenSRE treats bringing the base branch in as the fix. It does **not** open a new PR. Merged or closed PRs are refused — if the failure already landed on the base branch, ask for the branch itself ("fix the CI on main").

In branch mode OpenSRE reads the failing workflow runs on the branch's head commit, creates a fresh `opensre/ci-fix-*` repair branch in the isolated checkout (or a linked worktree when you selected a local checkout), pushes that branch, and waits for the pushed commit's own workflow runs. It does **not** push directly to `main` unless you ask for that. When you explicitly ask to push straight to the branch ("push straight to main", "commit directly to main"), OpenSRE makes the fix in a fresh clone of that branch, commits it there, pushes it without force, and verifies that commit's workflow runs. If `main` moved during the repair, nothing is pushed. If a branch protection rule requires a pull request, GitHub refuses the push and OpenSRE reports that; ask for a repair branch instead.

## Verify

There is no dedicated `integrations verify` target. Confirm readiness by:

1. An authorized GitHub connection in the OpenSRE app
2. `gh` available on `PATH`
3. If supplying a checkout explicitly, its `origin` matches the PR repository
4. An LLM is configured for OpenSRE (the built-in agent uses it when no coding agent CLI is ready)

If a worker stops after pushing, retry the repair to resume verification of
the recorded commit. A concurrent update to the PR stops verification of the
older commit.

## Troubleshooting

| Symptom | Fix |
| - | - |
| **Fork PR refused** | Only same-repository PR head branches are supported |
| **No push when checks are green** | Expected — OpenSRE does not push when nothing is failing |
| **"blocked on N file(s) a person must decide"** | The coding agent could not resolve those merge conflicts. The merge was aborted; resolve the listed files by hand, push, and run the fix again. If the message starts with "Pushed a CI fix", the fix commit is already on the branch and only the base merge is missing. When the agent named a choice only a person can make, OpenSRE also comments it on the PR and skips that PR until new commits land on it |
| **Approval prompts** | Appear at `/auto med` or lower; the default `/auto high` runs the repair without them |
| **gh / checks unavailable** | Install GitHub CLI and ensure the token can read Actions checks |

## Security

* Asks before mutating the working tree or pushing when the autonomy level is `/auto med` or lower.
* Pushes only to the existing PR head branch in the same repository.
* For branch targets, creates and pushes a fresh repair branch unless you explicitly ask to push straight to the branch; a direct push is never forced.
* Store tokens in `.env` or your secret manager — not in source control.


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