Skip to main content

CI Integration

You don't need a .appilotsrc file in CI at all. Set APPILOTS_API_KEY (and, optionally, APPILOTS_PROJECT_ID and APPILOTS_SERVER_URL) as CI secrets/environment variables, then run:

appilots sync --json

or, without a global install:

npx appilots sync --json

--json prints a machine-readable result on stdout (it implies --quiet), so a later pipeline step can parse the outcome. The process exits non-zero on failure, so a CI step naturally fails the build if the sync fails — no extra error handling required.

Example: GitHub Actions​

- name: Sync Appilots MCP document
  run: npx --yes @appilots/cli sync --json
  env:
    APPILOTS_API_KEY: ${{ secrets.APPILOTS_API_KEY }}
    APPILOTS_SERVER_URL: https://api.appilots.com

Store APPILOTS_API_KEY in your CI provider's secret store, never in a committed file or workflow YAML. See Configuration for why the CLI's http://localhost:4000 default must not leak into a production pipeline — always set APPILOTS_SERVER_URL explicitly, as above.

Where to put the step​

Run appilots sync after your build/test steps, so it only uploads once the change is verified — and gate it behind the same branch protections as your deploy.

--force is rarely needed​

sync skips the upload when the local checksum matches the last run and the server already has an active document for it. That's exactly what you want in CI: re-running sync on every commit is cheap and idempotent, so it's safe to run unconditionally as a required job step rather than gating it behind a manual trigger. Reach for --force only when you specifically need to re-upload despite an unchanged checksum — it's not something a normal CI job should pass by default.

Add --strict-metadata to fail the build if any mutating action is missing effect/riskLevel metadata, catching it before it reaches production instead of after. See Metadata quality for what the flag checks and how to fix a warning.

appilots sync --json --strict-metadata

Also gate on agent behavior​

Metadata quality catches missing risk annotations; it doesn't catch the agent actually doing the wrong thing after your UI changes. Run appilots eval right after sync to catch that class of regression too — see Testing your agent between releases.

Last updated on