# GitHub Actions

> Configure a bounded GitHub integration, understand comment triggers and runner authority, and distinguish a dry run from remote comments, pushes, and PRs.

Source: https://kaitoi.io/docs/cli/github-actions/
Section: Kaitoi CLI / Editors and automation
Written for: Repository maintainers configuring a Code automation.
Prerequisites: A disposable Linux X64 or ARM64 runner with repository checkout; A Kaitoi developer key with cli:code scope and appropriate GitHub permissions
Last reviewed: 2026-10-24

---

The GitHub integration can answer questions, review pull requests, and prepare
requested fixes. It invokes `kaitoi code github run` on the runner. This guide
describes the checked-in CLI **0.9.0** action contract; it does not assume a
published Marketplace action or invent a reusable release reference.

## Wire the runner to the command

The composite action lives at `tools/kaitoi-code-action/action.yml` in the
Kaitoi source tree. If you use a local action, its `uses` path must point to that
action in the runner's actual checkout. Alternatively, install the intended CLI
version and invoke `kaitoi code github run` in your own workflow step.

The command reads `GITHUB_EVENT_NAME`, `GITHUB_EVENT_PATH`, `GITHUB_WORKSPACE`,
`GITHUB_TOKEN`, and the Kaitoi account token. Store credentials as repository or
organization secrets. Configure checkout and GitHub token permissions for the
specific behavior you want: reading a PR, posting a response, and pushing a fix
have different needs.

## Choose the action inputs

| Input                  | Default or requirement                                         |
| ---------------------- | -------------------------------------------------------------- |
| `kaitoi-api-token`     | Required developer key with `cli:code`.                        |
| `github-token`         | Runner's `github.token`.                                       |
| `cli-version`          | `latest`; pin the intended release when repeatability matters. |
| `trigger`              | `/kaitoi`.                                                     |
| `review-on-open`       | `false`.                                                       |
| `provider`, `model`    | Optional selection.                                            |
| `max-credits`          | `200`; checked between model steps.                            |
| `allowed-associations` | `OWNER,MEMBER,COLLABORATOR`.                                   |
| `allow-commands`       | `false`; enabling grants fix command authority on the runner.  |

The action supports Linux X64 and ARM64 runners and verifies downloaded archive
and AppImage checksums before execution. Review the action's current input names
and your event/token setup together when adopting it.

## Understand which event starts which task


A qualifying trigger on a pull request requests review; a non-fix request on
an issue asks a question. A fix request can produce a branch and commit, then
push and open or update a pull request when authorized. Event and author checks
happen before work. Dry run removes remote writes but still runs the model and
can create a local fix branch and commit.

In the illustrated pull-request fix, an authorized remote write pushes to the existing PR branch and replies. Opening a new PR belongs to a different issue-fix path. The dry-run switch retains the local artifact while closing the remote-write path.

*Figure: Authorized GitHub events select a question, review, or fix path.*

A `/kaitoi` line on a PR asks for a review; `/kaitoi fix ...` requests a fix.
The trigger must begin a line, with at most three leading spaces. Matching is
case-insensitive and ignores fenced code and quoted replies. A non-fix issue
request asks a question.

When automatic review is enabled, opened, synchronize, and ready-for-review
events can trigger it; draft PRs are skipped. Manual `workflow_dispatch` requires
a prompt. Author associations are checked. **`pull_request_target` is explicitly
refused**; it is not a supported shortcut for making secrets available to a PR.

## Review write and cost authority

Fixes may create a branch and commit, push, and open a pull request. A same-repo
PR fix can update that PR's branch; protected or default branch pushes are
refused. Grant only the remote write permissions you intend.

`--dry-run` suppresses remote comments, reviews, pushes, and PR writes, but it
**still runs the model and can create a local fix branch and commit**.
`--allow-commands` is authority to execute fix commands on the disposable runner.
Neither option is a free simulation. The credit bound is checked between model
steps; the current step may take the total beyond it. Review the logs, diff,
checks, and returned result before integrating a fix.