# Fix Failing GitHub Actions Checks in a Koa API

Yes. When CI fails on your Koa API, an agent reads why the workflow stopped, updates its runner, actions and Node version, reruns the checks, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/fix-failing-ci/koa/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent starts with the workflow rather than the code, because on a repository like javieraviles/node-typescript-koa-rest the failure is in the workflow itself. `.github/workflows/ci.yml` runs both jobs on `ubuntu-16.04`, a runner label GitHub retired, so a push does not fail a step: the run is marked failed with an annotation that no runner matched the labels, and `gh run view --log-failed` has no log to show. The `build` job uses `actions/checkout@master` and `actions/setup-node@v1` with Node `12.x`, then `npm ci`, `npm run build` and `npm run test`; the `deploy_to_heroku` job builds a Docker image and uses an action under `actions/heroku` pinned to `master`, with `HEROKU_APP` and other values from secrets. `package.json` declares `engines.node` as `14.x.x`, so even a job that started would test a version the project says it does not support.

It then reads what the jobs would run once they start. `npm run build` is `npm run lint && npm run build-ts && npm run copy-static-assets`, where `lint` is `tsc --noEmit` followed by ESLint 7 with `--fix` over `**/*.{js,ts}`, `build-ts` is `tsc` with TypeScript 4.2 and the `experimentalDecorators` and `emitDecoratorMetadata` flags `tsconfig.json` sets for TypeORM and `koa-swagger-decorator`, and `copy-static-assets` runs `copyStaticAssets.ts` with `ts-node`. `npm test` is Jest 26 through `ts-jest` over `tests/**`, with `tests/controller/user.test.ts` mocking `typeorm` and `class-validator` so no database is needed. The `Dockerfile` the deploy job builds starts from `node:14-alpine` and runs the same `npm run build`.

The fix is confined to the workflow. The agent moves both jobs to `ubuntu-latest`, replaces `actions/checkout@master` with a pinned `actions/checkout@v4` and `actions/setup-node@v1` with `actions/setup-node@v4` using `node-version-file` on a new `.nvmrc` carrying the 14 that `engines` declares and the Dockerfile uses, and adds npm caching through the action's `cache` input. It keeps the job graph, `deploy_to_heroku` after `build`, limits the deploy job to pushes on `master` with an `if` so pull requests from branches do not try to deploy, and replaces the unpinned Heroku action with the Heroku CLI steps the job's image push needs, reading the same secrets. Every action reference gets a comment with the version it was moved from.

In its sandbox the agent installs Node 14 with the version file, runs `npm ci`, `npm run build` and `npm test` to show the two steps the `build` job runs pass on that version, then runs `act` or `actionlint` over the workflow to check the syntax and the action inputs it changed. It builds the Dockerfile once to confirm the image the deploy job pushes still builds with the same lockfile, and pastes the three outputs into the pull request. It pushes nothing to Heroku and sets no secret.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "The GitHub Actions workflow on this branch failed; the workflow_run event is at the end of this prompt. Read .github/workflows/ci.yml, package.json, package-lock.json's header, tsconfig.json, .eslintrc, Dockerfile, docker-compose.yml and tests/ first, and read the failed run with gh run view <run id> --log-failed; if the run has no log because no runner matched its labels, say so and quote the annotation. Fix the workflow only: move the jobs to a current Ubuntu runner, pin checkout and setup-node to current major versions, install the Node version the engines field and the Dockerfile agree on through a version file, add npm caching, keep the build then deploy order, restrict the deploy job to pushes on the default branch, and replace the unpinned Heroku action with explicit CLI steps that use the same secrets. Install that Node version in your sandbox, run npm ci, npm run build and npm test, lint the workflow with actionlint, build the Dockerfile, and open a pull request that pastes those outputs and the annotation you read. Do not change application code, the Dockerfile or any dependency version.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `.github/workflows/ci.yml` and adds `.nvmrc`, and nothing else. Its description quotes the annotation from the failed run, explains that a retired runner label fails a run before any step logs, and pastes the output of `npm run build` and `npm test` on Node 14 from the sandbox, the `actionlint` result for the new file, and the Docker build summary.

A table in the description lists each action reference with its old and new version and the reason, and a paragraph explains the `if` on the deploy job and the CLI steps that replace the Heroku action, naming the secrets they read so a reviewer can check them against the repository's settings without the agent ever seeing a value.

Before merging, a reviewer decides whether to move `engines` and the Dockerfile from Node 14 to a supported release in a separate change, whether the deploy should stay on Heroku at all, and whether to pin the actions to commit SHAs rather than major tags.

## Run it on every workflow run that ends in failure

Add a webhook for GitHub's `workflow_run` event and have a handler on your server send this request whenever a run completes with `conclusion: failure`, with the failing branch as `https://github.com/<owner>/<repo>/tree/<head_branch>` in `resources` so the clone is that branch and the event's JSON appended to `input`. GitHub signs its deliveries and cannot add an `Authorization` header, so the handler is what calls Rush, and it should skip branches the agent itself opened so a failed fix does not start another run.

Send a `request_id` that is a UUID v5 of the run id, so GitHub's redeliveries of the same event return the run already started rather than a second one. A `webhook_url` on the key reports `run.completed` with the pull request in `result`, and a key runs at most `max_concurrent` runs at once, 4 by default; a run past that is created `queued` and starts as a slot frees, so a noisy day needs no retry loop.

## Why run it on Rush?

A workflow that fails before its first step leaves no log to read, which is why this kind of red build sits for months: the usual loop of reading the failed step and fixing the test has nothing to start from. The agent reads the annotation, the runner label and the action versions, then proves the fix the only way available, by running the job's own commands on the right Node version in its own sandbox and linting the workflow it wrote.

The commands, the outputs and the Docker build stay with the run and in the pull request, so the review is reading evidence rather than trusting a YAML diff. The same request works for every repository a team keeps, one sandbox and one pull request each.

## Frequently asked questions

### Why is there no failed step in the log?

Because the jobs ask for `ubuntu-16.04`, a runner label GitHub no longer provides, so the run fails at scheduling with an annotation rather than at a step. The agent quotes that annotation in the pull request and treats the workflow file, not the tests, as the bug.

### Does it upgrade Node?

No. `engines` and the Dockerfile both say Node 14, so the workflow installs 14 through a new `.nvmrc` and the agent runs the build and tests on it in the sandbox. Moving the project to a supported Node release is named as a separate change for the reviewer.

### What happens to the Heroku deploy?

The job stays, after `build`, limited to pushes on the default branch, with explicit Heroku CLI steps in place of the unpinned action and the same secret names. The agent pushes nothing and never sees a secret value; whether to keep deploying to Heroku is the reviewer's call.

### Will the tests pass on the new runner?

The agent runs `npm ci`, `npm run build` and `npm test` on Node 14 in its sandbox and pastes the output; the Jest tests mock TypeORM and `class-validator`, so they need no database. The first run on the new workflow is the final check, and the pull request's own checks show it.

## More Koa jobs

- [Move a Koa Project from Travis CI to GitHub Actions](https://getrush.ai/run/migrate-travis-to-github-actions/koa/)
- [Write Supertest Tests for a Koa App](https://getrush.ai/run/write-supertest-tests/koa/)
- [Write the Missing Jest Tests for a Koa API](https://getrush.ai/run/write-unit-tests/koa/)

## The same job on other stacks

- [Fix Failing GitHub Actions Checks in a Laravel App](https://getrush.ai/run/fix-failing-ci/laravel/)
- [Fix Failing GitHub Actions Checks in a NestJS API](https://getrush.ai/run/fix-failing-ci/nestjs/)
- [Fix Failing GitHub Actions Checks in a Next.js App](https://getrush.ai/run/fix-failing-ci/nextjs/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
