# GitHub Action

One-line CI setup. Start an aimock server in GitHub Actions with a single `uses:` step.

## Quick Start

workflow.yml yaml

    - uses: CopilotKit/aimock@v1
      id: mock
      with:
        fixtures: ./test/fixtures

    - run: pnpm test
      env:
        OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1

## Inputs

Input | Default | Description
--- | --- | ---
`fixtures` | `./fixtures` | Path to fixture files or directory
`config` | — | Path to aimock JSON config file (overrides fixtures)
`port` | `4010` | Port to listen on
`host` | `127.0.0.1` | Host to bind to
`version` | `latest` | aimock version to install
`args` | — | Additional CLI arguments
`wait-timeout` | `30` | Max seconds to wait for health check

## Outputs

Output | Description
--- | ---
`url` | The aimock server URL (e.g., `http://127.0.0.1:4010`)

## Examples

### Basic with fixtures

workflow.yml yaml

    steps:
      - uses: actions/checkout@v4
      - uses: CopilotKit/aimock@v1
        id: mock
        with:
          fixtures: ./fixtures
      - run: npm test
        env:
          OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1

### Full suite with config

workflow.yml yaml

    steps:
      - uses: actions/checkout@v4
      - uses: CopilotKit/aimock@v1
        id: mock
        with:
          config: ./aimock.json
          args: --strict
      - run: npm test
        env:
          OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1

### Record mode (proxy to real APIs)

workflow.yml yaml

    steps:
      - uses: actions/checkout@v4
      - uses: CopilotKit/aimock@v1
        id: mock
        with:
          fixtures: ./fixtures
          args: --record --provider-openai https://api.openai.com
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      - run: npm test
        env:
          OPENAI_BASE_URL: ${{ steps.mock.outputs.url }}/v1

### Using the URL output

workflow.yml yaml

    steps:
      - uses: CopilotKit/aimock@v1
        id: mock
        with:
          fixtures: ./fixtures
      - run: echo "Mock server at ${{ steps.mock.outputs.url }}"

## How It Works

1. Installs `@copilotkit/aimock` via npm
2. Starts the server in the background
3. Polls `/health` until the server is ready (up to `wait-timeout` seconds)
4. Exports the URL as a step output
5. The server runs for the duration of the job and is cleaned up automatically