Skip to main content
Your repository owns the agent command. Firedrill supplies the isolated world, evaluates recorded consequences, and retains the result. Use pinned registry clients and firedrill ci run. Your repository can remain private.

​
Connect the repository

The application integration requires GitHub to be enabled, the Firedrill GitHub App installed for the repository, and a connected project and environment.
  1. Open Repository under Source and choose Connect repository.
  2. Install the GitHub App for the intended repository if required.
  3. Choose the repository and branch.
  4. Choose Find configuration and select the intended firedrill.json.
  5. Choose Review connection, review the exact repository and source root, then confirm the full repository name.
The repository must already contain reviewed Firedrill source. There is no current firedrill init command; use a downloaded source draft or your existing source. If GitHub integration is unavailable, ask your administrator to configure it. The CLI does not create or bypass the repository connection.

​
Configure the workflow

Create a GitHub Actions workflow under .github/workflows/ using the CI client setup. Select your connected project, environment, repository binding, and suite. Configure the triggers your repository needs. The job must:
  • Check out exact base and head revisions for a pull request, or the exact revision for another trigger.
  • Request contents: read and id-token: write.
  • Set up Node.js 24.
  • Install @firedrill-run/cloud@0.1.6 and @firedrill-run/ci-client@0.1.0.
  • Run firedrill ci run --auth github with the selected project, environment, repository binding, suite, revision, and agent command.
Set --agent-command and --agent-arguments to an actual non-interactive runner in your repository. Add its runtime, dependency installation, build steps, and narrowly scoped provider secrets. Firedrill does not create the adapter or infer those requirements. OIDC exchange issues short-lived Firedrill authority for the verified workflow invocation. No long-lived Firedrill key belongs in this GitHub workflow. Check out the exact authorized commit—not a branch name or synthetic merge commit.

​
Agent command contract

The CI client always runs the explicitly configured command in a separate process, even when the source target declares a different launcher. Its target identity, declared interfaces, and timeout remain in force. For example, this selects your existing Python adapter:
This is an argument fragment, not a complete invocation. The adapter file must already exist. The process receives one invocation JSON value on standard input: World values are also placed in the child process environment. Declared HTTP or MCP bindings use FIREDRILL_HTTP_URL / FIREDRILL_HTTP_TOKEN or FIREDRILL_MCP_URL / FIREDRILL_MCP_TOKEN; use only the values actually issued for the interaction. Write one JSON value to standard output and human-readable logs to standard error. Use a nonzero process exit for invocation failure. A successful subprocess or an agent’s claimed success is not the assertion verdict. The launcher does not use a shell. It sanitizes runner/control and dynamic-loader environment variables before adding world bindings. Configure only the provider secrets the agent needs at the workflow step. This process boundary is not an OS sandbox: do not give untrusted agent code access to unrelated files or host secrets.

​
Review results

A completed configured suite can publish a check on the exact candidate commit, a pull-request summary, a private evidence link, and a base-versus-head comparison after both results seal. The comparison reports factual changes in assertions, activity, and state. It does not infer that every difference is an improvement. Use CI → Run history for execution status. The client also writes reports under .firedrill/ci. See exit codes before configuring a required check. GitHub branch protection decides whether the check blocks merging. Start with focused invariants and use repeated trials for stochastic quality questions.

​
Captures and access

Choose capture policies explicitly; they default to off. The current CI subprocess adapter produces captured stderr logs only; it has no screenshot, video, or file-submission channel. Those policy flags do not create recordings or attachments. Use an SDK capture integration for additional artifacts. Evidence links remain private. Reviewers need project access or an explicit grant to the exact suite.