Copilot Fix Failing GitHub Actions: Setup and Review Rules

A red check on a pull request at 18:40 is the classic small tax: the fix is usually a lockfile, a lint rule or a test that moved, and it still costs a context switch. GitHub has now put a button on exactly that moment. Fix with Copilot sits on the failed run, and since July it sits on the failed check in GitHub Mobile too.

I have not run this on a production repository, so this is not a field report. It is a close reading of three GitHub changelog entries and four documentation pages, with every claim traced to a page I opened on 17 October 2026. Where the sources are silent, for example on cost, I say so rather than fill the gap. Claude Code has its own Actions integration, covered in the Claude Code GitHub Actions guide; this post is only about Copilot cloud agent.

What the button does, and the three dates it grew

The first entry is dated 18 May 2026. It adds a Fix with Copilot button to the workflow run logs page. Clicking it asks Copilot cloud agent to fix the failed job: the agent investigates in its own cloud-based development environment, pushes a fix to your branch and tags you for review. The launch audience was Copilot Business and Copilot Enterprise.

On 4 June 2026 a second entry extended the same button to Copilot Pro, Pro+ and Max subscribers. On 23 July 2026 GitHub Mobile gained it on the failed check of a pull request, with one difference worth noticing: Copilot opens a new pull request on top of your existing one rather than pushing into it, then tags you for review. The mobile entry names iOS and Android and does not say which plans qualify.

The documentation page for the desktop flow is short. The requirement is that the workflow run fails on a pull request branch. The steps are to open the job page for the failing run and click Fix with Copilot, after which Copilot starts a new session, looks into the cause and sends a fix to your branch. None of the four pages I read lists retry rules or a usage quota for this button.

What an admin has to switch on first

On Business and Enterprise the button is not yours to enable. The May entry says an administrator must turn on Copilot cloud agent before you can delegate to it. In the enterprise docs the path is AI controls, then Agents, then Copilot Cloud Agent under Available agents, where you pick a global policy. The page states the agent is disabled by default.

Scope has two levels. If you choose Enabled for selected organizations, you pick the organizations in the UI, and selecting them by custom properties needs the REST API. By default the agent is then available in every repository of those organizations; owners can block specific repositories at the organization level, and repository owners and administrators can disable it for a particular repository.

Rules can also lock the agent out. The about page warns that incompatible rulesets or branch protection rules can block its access, and that administrators can grant Copilot a bypass actor role. I would decide that bypass question deliberately, because it decides whether the agent can push at all on a protected branch. The June entry for Pro, Pro+ and Max lists only a qualifying plan and a failed job with logs as requirements; it names no admin step, and I did not find one documented for those plans.

What it pushes, where, and what it cannot touch

The risks page is the clearest statement of the write path. The agent can push to only one branch. If it was triggered by mentioning @copilot on a pull request, it writes to that pull request's branch; otherwise it creates a new copilot branch. Branch protections and required checks still apply, and the agent cannot run git push or other git commands directly. The about page adds that Copilot works on one branch at a time and opens one pull request per task.

Two limits matter for CI work. Each session has a maximum execution time of 59 minutes, which the page says cannot be extended or bypassed, so a failure that needs an hour of integration tests to reproduce is outside what this button can do. And only repositories hosted on GitHub are supported. The table puts the three ways of getting help on a failed run side by side, using only what the sources state.

Explain error is the lower-risk sibling. It only opens a chat window where Copilot gives instructions to resolve the issue, so nothing is pushed. I would use it first whenever I do not yet know whether the failure is code or infrastructure.

Give the agent the same environment your CI has

The agent runs in its own environment, and a fix it cannot test is a guess. The customisation docs describe a workflow file at .github/workflows/copilot-setup-steps.yml. It only triggers once it is on the default branch, and it must contain a single job named copilot-setup-steps, or Copilot will not pick it up. Only these keys in that job are honoured: steps, permissions, runs-on, services, snapshot and timeout-minutes.

Three behaviours from the same page are worth knowing. timeout-minutes has a maximum of 59. A fetch-depth you set on actions/checkout is overridden so the agent can roll back commits. And if a setup step exits non-zero, the remaining steps are skipped and Copilot starts with whatever state the environment reached, so a failed npm ci does not stop the session, it quietly gives you an agent without dependencies. The example below uses only the honoured keys; the install commands are mine, for a Node project.

# .github/workflows/copilot-setup-steps.yml
# Must be on the default branch, and the job MUST be named copilot-setup-steps.
# Only steps, permissions, runs-on, services, snapshot and timeout-minutes
# are honoured; anything else in the job is ignored.
name: "Copilot Setup Steps"

on:
  workflow_dispatch:          # run it by hand once to prove the steps pass
  pull_request:
    paths: [".github/workflows/copilot-setup-steps.yml"]

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest    # Ubuntu x64 or Windows 64-bit only
    timeout-minutes: 30       # 59 is the documented ceiling
    permissions:
      contents: read          # needed because the steps clone the repository
    steps:
      - uses: actions/checkout@v4   # fetch-depth is overridden by Copilot anyway
      - uses: actions/setup-node@v4
        with:
          node-version-file: ".nvmrc"
          cache: npm
      # A non-zero exit here skips the remaining steps and the session STILL
      # starts, just without dependencies. Keep this step fatal in CI terms
      # by running the same command your real workflow runs.
      - run: npm ci

The same page says the agent supports Ubuntu x64 Linux and Windows 64-bit runners only, and that self-hosted runners need Copilot's integrated firewall disabled because it is not compatible with them. If your failing job runs on macOS, the agent cannot reproduce it.

The approval gap: its pushes do not run your checks

This is the part I would brief the whole team on. The Copilot documentation says that by default GitHub Actions workflows do not run automatically when Copilot pushes changes to a pull request; you may need to click Approve and run workflows in the merge box. The risks page frames it as a mitigation: workflows do not run until the code is reviewed and a user with write access clicks that button, with an option to allow automatic runs.

The consequence is a trap for anyone who reads status at a glance. After the agent pushes, the pull request can still show the old red check or no fresh check at all, depending on how your branch protection is set up. The fix has not been verified by your CI yet. The commands below ask the question that matters: did a run happen on the commit the agent pushed, and what did it conclude.

PR=123

# The commit the agent pushed (the PR head), and the branch it lives on.
HEAD_SHA=$(gh pr view "$PR" --json headRefOid --jq .headRefOid)
BRANCH=$(gh pr view "$PR" --json headRefName --jq .headRefName)

# Wrong: trust the rollup on the PR page. It may describe an older commit,
# or nothing, if workflows are still waiting for "Approve and run workflows".
gh pr checks "$PR"

# Right: ask whether any run exists for exactly this commit, and what it said.
gh run list --branch "$BRANCH" --limit 10 \
  --json databaseId,event,headSha,status,conclusion \
  --jq ".[] | select(.headSha == \"$HEAD_SHA\")"
# Empty output means CI has not verified the agent's fix yet.

Review rules that keep the fix honest

GitHub's review controls are on your side here, and they are specific. A human must review and merge pull requests the agent opens; it cannot mark them ready, approve them or merge them. The user who asked Copilot to create a pull request cannot approve it. If a pull request is not attributed to a person and the repository requires at least one approval, one more approval is required. That extra approval is on by default in rulesets, where admins can turn it off, and always applies to branch protection rules.

The table maps each control from the risks page to the failure it addresses. The CODEOWNERS file after it is my addition, not something the sources prescribe: it makes sure the files an agent could weaken to get a green check always need a named human.

# .github/CODEOWNERS
# The files an agent could weaken to turn a red check green always need a
# named human, whoever (or whatever) opened the pull request.
/.github/workflows/   @acme/platform-team
/.github/CODEOWNERS   @acme/platform-team
/tests/               @acme/qa-owners
/eslint.config.mjs    @acme/platform-team
/package-lock.json    @acme/platform-team

The last row is why I read the risks page with some care. The agent reads failing job logs, and logs echo whatever your tests and tools print. The page documents filtering of hidden characters in issues and comments, but I found no statement about log content, so I treat logs as untrusted input and keep the agent's token scope small.

Where this goes wrong: green by weakening

The cheapest way to turn a red check green is to change the check. A test is skipped, a lint rule is relaxed, a timeout is raised, a workflow condition is loosened. The sources do not report the agent doing this; they do say output may be incorrect or insecure, that logs do not replace your own review and testing, and that you should review and test the output before using it in production. I read that as a prompt to look for exactly this shape of change.

So I review the agent's diff in a fixed order: first anything under the workflow directory and the test directories, then dependency files, then the source change that was supposed to be the fix. A fix that mostly lives in the first two groups is a change to the definition of success, and deserves the question of why the code itself did not need to change.

# Review order for an agent fix. Read the "definition of success" first.
BASE=origin/main

# 1. Did it touch the checks themselves? Any hit needs a written reason.
git diff --stat $BASE...HEAD -- .github/ tests/ '*.test.*' '*.spec.*'

# 2. Did it quietly skip or loosen something?
git diff $BASE...HEAD | grep -nE '^\+.*(\.skip|xit\(|xdescribe|eslint-disable|continue-on-error|timeout-minutes)'

# 3. Dependencies, then finally the source change that was meant to be the fix.
git diff --stat $BASE...HEAD -- package.json package-lock.json
git diff $BASE...HEAD -- src/

The other limits are structural. Failures caused by an expired secret, a flaky third-party service or a runner outage are not code problems, and an agent session that spends its 59 minutes on them produces a plausible patch for the wrong cause. Read the first failing step yourself before you press the button, and press it for failures that are about code.

What to do on Monday

Five steps, in order, each small enough to finish in an afternoon.

1. Ask the enterprise or organization admin whether Copilot cloud agent is enabled, and on which repositories. On Business and Enterprise it is disabled by default.
2. Add copilot-setup-steps.yml to the default branch with the same toolchain and install step as your CI, and run it once by hand to confirm it succeeds.
3. Decide the ruleset question: does Copilot get a bypass actor role, and is the extra-approval rule left on for agent-authored pull requests.
4. Add CODEOWNERS entries for the workflow and test directories so the files an agent could weaken always need a named reviewer.
5. Write the review order from the previous section into your pull request template, and make approving the workflow run an explicit, post-diff step.

After the first agent fix, check whether a run happened on its head commit, and note the cost. The pages I read describe usage only by link to a billing page, so I cannot tell you what a session costs; look at your own billing and usage before you widen the rollout.

Fix with Copilot is a good delegation for failures that are plainly about code, and a poor one for failures about the world around it. The rule I would carry is this: the agent may propose a fix, but your CI has to verify it, and a human has to read what changed in the checks themselves before anything merges.