GitHub Actions

hitspec integrates with GitHub Actions through an official action and direct CLI usage. You can run API tests on every push, pull request, or schedule, and report results using JUnit XML.

Official GitHub Action

The fastest way to add hitspec to your pipeline:

.github/workflows/api-tests.yml

name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          output: junit
          output-file: test-results.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results
          path: test-results.xml

Action Inputs

Input	Description	Default
`files`	Files, directories or glob patterns, separated by whitespace or newlines (see Selecting files)	(required)
`env`	Environment name. When empty, hitspec uses `defaultEnvironment` from `hitspec.yaml`	-
`env-file`	Path to `.env` file for variable interpolation	-
`output`	Output format (`console`, `json`, `junit`, `tap`, `html`)	`console`
`output-file`	Write the report to this file. Defaults to `hitspec-results.<ext>` for `json`, `junit`, `tap` and `html`	-
`tags`	Filter by tags (comma-separated)	-
`name`	Filter by request name pattern	-
`timeout`	Request timeout: a duration such as `30s` or `1m`, or a plain integer meaning milliseconds (`5000` is `5000ms`)	-
`parallel`	Run requests in parallel	`false`
`concurrency`	Max concurrent requests when `parallel` is enabled	-
`bail`	Stop on first failure	`false`
`verbose`	Show detailed output	`false`
`insecure`	Disable SSL certificate validation	`false`
`proxy`	Proxy URL for requests	-
`stress`	Enable stress testing mode	`false`
`duration`	Stress test duration (e.g. `30s`, `1m`)	`30s`
`rate`	Target requests per second for stress testing	`10`
`vus`	Number of virtual users (alternative to `rate`)	-
`max-vus`	Maximum concurrent requests in stress mode	-
`think-time`	Think time between requests per VU	-
`ramp-up`	Ramp-up time to reach target rate/VUs	-
`threshold`	Pass/fail thresholds (e.g. `"p95<200ms,errors<0.1%"`)	-
`profile`	Stress profile name from `hitspec.yaml`	-
`version`	hitspec release to install (e.g. `v2.20.0` or `latest`)	`latest`

Selecting files

files takes one or more paths separated by spaces or newlines. Directories and glob patterns are both accepted, and a pattern that matches nothing fails the step instead of silently testing nothing:

- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: |
      tests/smoke/
      services/**/*.http

** matches across directories when the runner’s bash is version 4 or newer (Linux and Windows runners); with bash 3.2 (the macOS system shell) it behaves like a single *, so list one pattern per directory level there. Paths that contain spaces are not supported.

Reports

With the default output: console the results are printed in the log. When you choose a machine-readable format (json, junit, tap or html) the report is written to output-file, or to hitspec-results.<ext> (.json, .xml, .tap, .html) when you do not set one, so it never floods the log. Use the report-file output to find it:

- uses: abdul-hamid-achik/hitspec@v2
  id: hitspec
  with:
    files: tests/
    output: junit

- uses: actions/upload-artifact@v7
  if: always()
  with:
    name: test-results
    path: ${{ steps.hitspec.outputs.report-file }}

Action Outputs

Output	Description
`exit-code`	Exit code from hitspec (`0` = success, non-zero = failure)
`report-file`	Path of the report file (empty for `console` output without `output-file`)
`version`	The hitspec release that was installed, for example `v2.20.0`

Installation, platforms and verification

The action downloads the hitspec release archive from GitHub Releases (with retries), verifies its SHA-256 against the checksums.txt published with the same release, and adds the binary to PATH for the following steps. A checksum mismatch fails the step. It supports Linux, macOS and Windows runners on amd64 and arm64. With version: latest the release is resolved through the public releases/latest redirect, so no API quota is used. The step fails whenever hitspec exits non-zero. Combine it with continue-on-error: true and steps.<id>.outcome if a failing test run should not stop the job.

Pinning the action

@v2 is a floating tag that moves to the latest v2.x.y release. Pin to a specific release tag (for example @v2.20.0) or a commit SHA for fully reproducible workflows. The older @v1 tag is frozen and still contains the previous, less robust implementation of the action; move to @v2.

Using the CLI Directly

If you prefer installing hitspec yourself (for example, to pin a specific version or use Homebrew caching), you can call the CLI directly:

.github/workflows/api-tests.yml

name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install hitspec
        run: |
          # Choose a published version from the Releases page:
          # https://github.com/abdul-hamid-achik/hitspec/releases/latest
          VERSION=2.18.0
          curl -fsSL "https://github.com/abdul-hamid-achik/hitspec/releases/download/v${VERSION}/hitspec_${VERSION}_linux_amd64.tar.gz" | tar xz
          sudo mv hitspec /usr/local/bin/

      - name: Run API tests
        run: |
          hitspec run tests/ \
            --env staging \
            --output junit \
            --output-file test-results.xml \
            --bail

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results
          path: test-results.xml

Exit Codes

hitspec uses specific exit codes that GitHub Actions interprets as pass or fail:

Code	Meaning	CI Result
`0`	All tests passed	Step passes
`1`	One or more tests failed	Step fails
`2`	A file could not be loaded (invalid `.http` syntax, duplicate `@name`, `@depends` cycle)	Step fails
`3`	Configuration error (broken `hitspec.yaml`, missing `--env-file`, bad CA, certificate, key or proxy)	Step fails
`4`	Network error: a request got no response because the connection failed	Step fails
`64`	Usage error (unknown flag, bad value, missing argument), or `--name`/`--tags` matched no request	Step fails
`130`	Interrupted (Ctrl+C or SIGTERM)	Step fails

Any non-zero exit code causes the GitHub Actions step to fail, which blocks the workflow (and any required status checks) from passing.

Environment Variables and Secrets

Use GitHub secrets to pass sensitive values like API tokens and credentials. hitspec supports all major CLI flags as environment variables with the HITSPEC_ prefix.

- uses: abdul-hamid-achik/hitspec@v2
  env:
    API_TOKEN: ${{ secrets.API_TOKEN }}
    HITSPEC_ENV: staging
    HITSPEC_TIMEOUT: 60s
    HITSPEC_BAIL: "true"
  with:
    files: tests/
    output: junit
    output-file: test-results.xml

Using an `.env` File

If your tests rely on an environment file, generate it from secrets at runtime:

- name: Create environment file
  run: |
    echo "API_TOKEN=${{ secrets.API_TOKEN }}" >> .env.ci
    echo "DB_URL=${{ secrets.DB_URL }}" >> .env.ci

- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    env: staging
    env-file: .env.ci

Supported Environment Variables

Environment Variable	CLI Flag	Description
`HITSPEC_ENV`	`--env`	Environment to use
`HITSPEC_ENV_FILE`	`--env-file`	Path to `.env` file
`HITSPEC_CONFIG`	`--config`	Path to config file
`HITSPEC_TIMEOUT`	`--timeout`	Request timeout
`HITSPEC_TAGS`	`--tags`	Filter by tags
`HITSPEC_OUTPUT`	`--output`	Output format
`HITSPEC_OUTPUT_FILE`	`--output-file`	Output file path
`HITSPEC_BAIL`	`--bail`	Stop on first failure
`HITSPEC_PARALLEL`	`--parallel`	Run in parallel
`HITSPEC_CONCURRENCY`	`--concurrency`	Concurrent requests
`HITSPEC_QUIET`	`--quiet`	Suppress output
`HITSPEC_NO_COLOR`	`--no-color`	Disable colors
`HITSPEC_PROXY`	`--proxy`	Proxy URL
`HITSPEC_INSECURE`	`--insecure`	Skip SSL verification

Each variable sits between its flag and hitspec.yaml: the flag wins over the variable, and the variable wins over hitspec.yaml. HITSPEC_BAIL=false turns off a bail: true in hitspec.yaml.

Metrics and Notification Variables

Environment Variable	CLI Flag	Description
`HITSPEC_METRICS`	`--metrics`	Metrics export format: `prometheus`, `datadog`, `json`
`HITSPEC_METRICS_PORT`	`--metrics-port`	Prometheus metrics port (default `9090`)
`HITSPEC_METRICS_HOST`	`--metrics-host`	Prometheus bind address (default `127.0.0.1`)
`HITSPEC_METRICS_FILE`	`--metrics-file`	Output file for JSON metrics
`DD_API_KEY`	`--datadog-api-key`	DataDog API key
`DD_SITE`	`--datadog-site`	DataDog site (default `datadoghq.com`)
`DD_TAGS`	`--datadog-tags`	Comma-separated DataDog tags
`HITSPEC_NOTIFY`	`--notify`	Notification service: `slack`, `teams`
`HITSPEC_NOTIFY_ON`	`--notify-on`	When to notify: `always`, `failure`, `success`, `recovery` (default `failure`)
`SLACK_WEBHOOK`	`--slack-webhook`	Slack webhook URL
`SLACK_CHANNEL`	`--slack-channel`	Slack channel override
`TEAMS_WEBHOOK`	`--teams-webhook`	Microsoft Teams webhook URL

Caching

Cache the hitspec binary to speed up subsequent runs:

- name: Cache hitspec binary
  uses: actions/cache@v5
  with:
    path: /usr/local/bin/hitspec
    key: hitspec-${{ runner.os }}-${{ hashFiles('.hitspec-version') }}

- name: Install hitspec
  run: |
    if ! command -v hitspec &> /dev/null; then
      # Choose a published version from the Releases page:
      # https://github.com/abdul-hamid-achik/hitspec/releases/latest
      VERSION=2.18.0
      curl -fsSL "https://github.com/abdul-hamid-achik/hitspec/releases/download/v${VERSION}/hitspec_${VERSION}_linux_amd64.tar.gz" | tar xz
      sudo mv hitspec /usr/local/bin/
    fi

If you install hitspec via Go, you can cache the Go module cache instead:

- uses: actions/setup-go@v6
  with:
    go-version: "1.26.x"
    cache: true

- name: Install hitspec
  run: go install github.com/abdul-hamid-achik/hitspec/v2/cmd/hitspec@latest

Matrix Testing

Run the same tests across multiple environments or configurations using a GitHub Actions matrix:

.github/workflows/api-tests.yml

name: API Tests (Matrix)

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        environment: [dev, staging, production]
    steps:
      - uses: actions/checkout@v6

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          env: ${{ matrix.environment }}
          output: junit
          output-file: test-results-${{ matrix.environment }}.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: test-results-${{ matrix.environment }}
          path: test-results-${{ matrix.environment }}.xml

Matrix with Tags

You can also use a matrix to run different test suites:

strategy:
  fail-fast: false
  matrix:
    include:
      - suite: smoke
        tags: smoke
        timeout: 30s
      - suite: integration
        tags: integration
        timeout: 120s
      - suite: contract
        tags: contract
        timeout: 60s

steps:
  - uses: actions/checkout@v6

  - uses: abdul-hamid-achik/hitspec@v2
    env:
      HITSPEC_TIMEOUT: ${{ matrix.timeout }}
    with:
      files: tests/
      tags: ${{ matrix.tags }}
      output: junit
      output-file: test-results-${{ matrix.suite }}.xml

Stress Testing in CI

Run load tests in your pipeline to catch performance regressions:

- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: api.http
    stress: true
    duration: 2m
    rate: 100
    threshold: "p95<200ms,errors<0.5%"

The threshold input defines pass/fail criteria. If any threshold is exceeded, the step fails with exit code 1.

Reporting with JUnit

Most CI reporting tools understand JUnit XML. To publish results in GitHub pull requests, combine hitspec with a JUnit reporter action:

- uses: abdul-hamid-achik/hitspec@v2
  with:
    files: tests/
    output: junit
    output-file: test-results.xml

- name: Publish Test Results
  uses: EnricoMi/publish-unit-test-result-action@v2
  if: ${{ !cancelled() }}
  with:
    files: test-results.xml
    comment_mode: off

This adds a test summary directly to the pull request checks tab. Grant the workflow or job token checks: write when publishing check runs.

Full Example Workflow

A complete workflow that runs smoke tests on every PR, full tests on main, and uploads results:

.github/workflows/api-tests.yml

name: API Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          tags: smoke
          output: junit
          output-file: smoke-results.xml
          bail: true

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: smoke-results
          path: smoke-results.xml

  full:
    runs-on: ubuntu-latest
    needs: smoke
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v6

      - name: Create environment file
        run: |
          echo "API_TOKEN=${{ secrets.API_TOKEN }}" >> .env.ci

      - uses: abdul-hamid-achik/hitspec@v2
        with:
          files: tests/
          env: staging
          env-file: .env.ci
          parallel: true
          output: junit
          output-file: full-results.xml

      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: full-results
          path: full-results.xml

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

Official GitHub Action

Action Inputs

Selecting files

Reports

Action Outputs

Installation, platforms and verification

Pinning the action

Using the CLI Directly

Exit Codes

Environment Variables and Secrets

Using an `.env` File

Supported Environment Variables

Metrics and Notification Variables

Caching

Matrix Testing

Matrix with Tags

Stress Testing in CI

Reporting with JUnit

Full Example Workflow

Official GitHub Action

Action Inputs

Selecting files

Reports

Action Outputs

Installation, platforms and verification

Pinning the action

Using the CLI Directly

Exit Codes

Environment Variables and Secrets

Using an .env File

Supported Environment Variables

Metrics and Notification Variables

Caching

Matrix Testing

Matrix with Tags

Stress Testing in CI

Reporting with JUnit

Full Example Workflow

Using an `.env` File