Fix GitHub CI - OpenSRE Documentation

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.

This is mutating. OpenSRE asks before checking out or creating a worktree, editing files, committing, and pushing.

Prerequisites

Git installed on the machine running OpenSRE
gh on PATH for checks and logs
GitHub token with repo write access plus workflow/check read access (GITHUB_TOKEN / GH_TOKEN)
A coding-agent backend available (CODING_AGENT=auto by default)

Setup

There is no dedicated integrations setup target for this tool. Configure GitHub access. A named repository or PR URL uses an isolated checkout. For requests about your current checkout, you can set the coding workspace:

export CODING_WORKSPACE=/path/to/repo  # optional, for current-checkout requests
export GITHUB_TOKEN=... # repo write access plus workflow/check read access
# optional:
# export CODING_AGENT=auto   # pi | claude-code | codex | cursor
# export CODING_MODEL=...

OpenSRE uses the configured coding-agent backend through CODING_AGENT=auto by default.

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	Local coding agent CLI when auto-detected

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:

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

What happens

OpenSRE reads PR metadata or the latest failing Actions run on the target branch.
It fetches compact log excerpts for failing Actions jobs.
It creates an isolated checkout for a named repository, or verifies that your explicitly selected checkout matches.
It refuses fork PRs because it only pushes to branches in the same repository.
After approval, it checks out the PR head branch or creates a temporary linked git worktree for a branch target such as main.
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.
If files changed, it commits only the fix-run changes and pushes the PR branch or fresh repair branch.
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 linked worktree on a fresh opensre/ci-fix-* repair branch, pushes that branch, and waits for the pushed commit’s own workflow runs. It does not push directly to protected branches such as main.

Verify

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

opensre integrations verify github (or a valid GITHUB_TOKEN / GH_TOKEN)
gh available on PATH
If supplying a checkout explicitly, its origin matches the PR repository
A coding agent CLI is installed/logged in if auto mode needs one

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
Approval prompts	Mutating path requires confirmation before checkout/edit/commit/push
gh / checks unavailable	Install GitHub CLI and ensure the token can read Actions checks

Security

Requires explicit confirmation before mutating the working tree or pushing.
Pushes only to the existing PR head branch in the same repository.
For branch targets, creates and pushes a fresh repair branch instead of pushing directly to main.
Store tokens in .env or your secret manager — not in source control.

​Overview

​Prerequisites

​Setup

​Credentials

​Tools

​Use it

​What happens

​Verify

​Troubleshooting

​Security

Overview

Prerequisites

Setup

Credentials

Tools

Use it

What happens

Verify

Troubleshooting

Security