Run Kiro CLI Headless in CI

Headless mode runs one prompt and exits, which is what a pipeline step needs. Give it a key through the environment, trust the smallest tool set that does the job, and it behaves like any other CI command.

When to use this

Use headless runs for unattended, repeatable work: nightly documentation regeneration, triage of new issues, a scheduled check on a codebase. Do not use it as a substitute for a human reviewer on a pull request that ships. An agent step in CI is automation, and automation needs the same suspicion as any other unattended process.

Steps

1. Get an API key and store it in your CI secret store. Never commit it and never echo it in a log.

2. Write the prompt so it produces the same shape of output every time. Deterministic and narrow beats clever:

   kiro-cli chat --no-interactive --trust-tools=read,grep \
     "Review the staged diff for missing error handling. List findings only."

3. Name the tool categories the job needs with --trust-tools. A review job needs read access, not write or shell. --trust-all-tools exists; treat it the way you would treat running a script as root.

4. Add --require-mcp-startup when the prompt depends on an MCP server. Without it, a pipeline can wait on a server that will never answer.

5. Pin the persona. Run as a restricted custom agent with --agent, so the tool ceiling lives in a reviewed file rather than in a shell line somebody may edit. See Create a custom agent.

6. Add the step to your pipeline. Only the Kiro-specific lines below are verified commands and flags; the rest is ordinary GitHub Actions structure, shown as an example.

   Example: .github/workflows/review.yml

   # Example skeleton. The Kiro-specific parts are the env var and the
   # kiro-cli command; adapt the rest to your own pipeline.
   jobs:
     review:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Install Kiro CLI
           run: curl -fsSL https://cli.kiro.dev/install | bash
         - name: Review the diff
           env:
             KIRO_API_KEY: ${{ secrets.KIRO_API_KEY }}
           run: |
             kiro-cli chat --no-interactive \
               --trust-tools=read,grep \
               --require-mcp-startup \
               "Review the diff on this branch for missing error handling."

7. Set a budget expectation. Every prompt consumes credits, and an unattended loop spends them without anyone watching.

Check it worked

Run the job on a branch with a known problem and confirm the finding appears in the log. Then run it on a clean branch and confirm the output is short. The second run matters more: a job that always reports something is noise, and the team will stop reading it.

Common problems

• Authentication fails. KIRO_API_KEY is not set in the job’s environment, or it is set on the wrong step. Environment variables do not carry across steps unless you set them at job level.
• The run hangs. An MCP server is not connecting. Add --require-mcp-startup.
• The job asks for approval and times out. The prompt needed a tool category you did not trust. Add the category, or narrow the prompt.
• Output varies run to run. The prompt is too open. Ask for a fixed shape, such as a list of findings with file and line.
• Credits disappear. Something runs on every push. Restrict the trigger, or run the job on a schedule.

Related

• Kiro CLI Guide covers the interactive commands and the headless flags.
• Create a custom agent gives the job a reviewed ceiling.
• Set up permissions.yaml is the deeper guardrail.