CI/CD

Because the project is in your repo, running requests in CI is just installing the CLI and calling craftr. Useful for smoke tests, contract checks, and deploy gates.

The basics

npm install -g @apicrafthq/cli
craftr req run Pet/get-pet -e staging

craftr prints JSON and exits non-zero when a request fails, so it composes with normal shell tooling and pipeline step semantics.

Supplying secrets

Secret values live in gitignored *.secrets.env files, so they aren't in the checkout. In CI, supply them through the environment instead: a declared variable apiKey is read from API_CRAFT_VAR_APIKEY (the variable name, uppercased, with the API_CRAFT_VAR_ prefix). Map your CI secret to that:

# .github/workflows/api-check.yml
name: API check
on: [push]
jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm install -g @apicrafthq/cli
      - name: Run a request
        env:
          API_CRAFT_VAR_APIKEY: ${{ secrets.API_KEY }}
        run: craftr req run Pet/get-pet -e staging | jq -e '.status == "available"'

The same effect for a one-off run is --var apiKey=….

Non-interactive import

If a step imports a spec, pass --yes so it never blocks on a prompt:

craftr schema import ./openapi.json -a petstore-api --yes

Running workflows

For multi-step tests, run workflows instead of chaining req run calls. craftr workflow run takes one or more workflow names (or --all) and an environment binding per API the run touches:

craftr workflow run pet-lifecycle --env petstore-api=staging
craftr workflow run --all -e petstore-api=staging -e catalog=staging

Like req run, it prints a JSON summary on stdout and exits non-zero if any workflow fails (1 failed, 130 cancelled), so it drops straight into a pipeline step:

      - name: Run workflows
        env:
          API_CRAFT_VAR_APIKEY: ${{ secrets.API_KEY }}
        run: |
          craftr workflow validate
          craftr workflow run --all \
            -e petstore-api=staging -e catalog=staging \
            --trust --full-output workflow-run.json

Three things worth doing in CI specifically:

• craftr workflow validate first. It checks that every block still resolves (api, operation, instance, script) without sending a request. A rename that broke a workflow fails the job in a second instead of halfway through a run.
• --trust if any workflow uses scripts. Scripts only run in a trusted project and there's nobody to click approve on a runner; --trust allows them for that one invocation and saves nothing. (craftr project trust is the persistent equivalent, for your own machine.)
• --full-output <file> to keep the per-block detail. Stdout only carries the summary, so without it a failed run leaves you with nothing to upload as a build artifact.

Secrets resolve the same way as single requests (above). See writing workflows → From the CLI for the full flag list.