Skip to main content
You want every pull request checked on a virtual board, and the job failed when a test fails. chiplab-cli runs the same test suite your agent writes, as one CI step. The step fails when a test fails or the suite does not run to completion. No agent runs in the pipeline.

What you’ll do

1

Create a personal access token

On API keys, create a personal access token. Name it after the pipeline, so you can revoke it on its own. Chiplab shows the token once. Store it as a repository secret named CHIPLAB_API_KEY.
2

Commit the board and the suite

Commit a JSON file with the board definition, the same object run_test_suite takes (see Boards):
Commit the suite file next to it. Your agent can write it for you (see test).
3

Pick a project

Use the project_id your agent already works in, from list_projects. Runs from CI show up in that project.
4

Add the workflow

Build the ELF in an earlier step of the same job, then install and run chiplab-cli:
veecle/install-chiplab installs the latest release. Set its version input to pin one.
For a complete workflow running in production, see chiplab-smoke.yml in the examples repository.

Ask your agent

What you get back

The step passes when every test passed. It fails when a test fails, the suite does not compile, or the run fails. Upload the artifacts even when the step fails. testsuite_stderr and firmware_uart are where to look first. See Reading the result.
Every run uses credits (see Usage). Run on pull requests rather than every push, or limit the workflow to the paths that change the firmware.

Run an agent in CI instead

When you want an agent to build, run, and diagnose in the pipeline, run it in the job and let it use Chiplab over MCP.
1

Connect the agent with the token

The job sends the personal access token as a bearer token:
CHIPLAB_API_KEY stays in the CI environment. The config file holds the ${CHIPLAB_API_KEY} placeholder, so the token is expanded when the job connects.
2

Start from the GitHub Actions template

The examples repository ships .github/workflows/claude-chiplab-smoke.yml. The template runs Claude Code in the job, which then uses Chiplab. It runs when someone comments /smoke-test on a pull request. It builds examples/bare-metal/stm32f4-discovery and checks the captured UART. It needs two secrets: CHIPLAB_API_KEY (a Chiplab personal access token, starts with veecle_pat_) and ANTHROPIC_API_KEY (for Claude Code). Treat it as a template: the trigger, the agent, and the example path are yours to change. Changing the on: trigger by itself is not enough. The job checks that the comment contains /smoke-test, and it checks out the pull request number from that comment.
3

Run on every pull request

To run on every pull_request, change the trigger, the job-level comment check, and the checkout together. A pull_request event has no comment body, and github.event.issue.number is empty.
Delete the job-level if. It looks for /smoke-test in the comment. Deleting it also drops the check that the commenter is OWNER, MEMBER, or COLLABORATOR.
Check out the pull request head:
The fork-guard step calls gh pr view with that same number. Point it at the pull request:
4

Fail when the expected output is missing

The job calls ask for the current boards, tools, and gotchas, produces an ELF, uploads it, runs it, and downloads uart. Fail the pipeline unless uart contains what you expect. The public examples expect Hello world!. The check must look at the uart output, not the run status, because a crashing firmware still returns succeeded.

Next

test

Write the checks the pipeline runs.

Chiplab CLI

Install the CLI and authenticate.
Last modified on November 2, 2026