CI/CD · CLI, GitHub Action, runners

Run API tests in CI

API tests in CI without a harness to maintain: install the CLI or drop in the GitHub Action, run your smoke tests by tag, and let exit codes decide the merge. Each run executes on an ephemeral runner that exists only for that job.

GitHub Action docs

exit 0 success · 1 flow failed · 2 cancelled · 3 contract/API error · 4 poll timeout up to 50 flows per tag run

Echopoint CLI

API testing from the CLI, in one command

The CLI installs with a single checksum-verified script — no sudo, straight to ~/.local/bin, with a PowerShell one-liner for Windows. Authenticate locally with echopoint auth login (browser OAuth), or in CI with the ECHOPOINT_API_KEY and ECHOPOINT_ORGANIZATION_ID environment variables.

echopoint flows run executes flows as one-shot ephemeral runs: pass flow IDs or --tag smoke to resolve a suite (repeatable, --match-mode any|all, up to 50 flows per run). Add --verbose for live node-by-node status in the terminal, -o json for machine-readable results, and --poll-timeout if a suite needs more than the default 30 minutes. The same tags can drive a schedule too — monitors watch between merges while CI gates each change.

installmacOS / Linux

curl -fsSL https://raw.githubusercontent.com/nanostack-dev/echopoint-cli/main/install.sh | sh

run locallyterminal

echopoint auth login
echopoint flows run --tag smoke --environment staging --verbose

run in ciapi key auth

ECHOPOINT_API_KEY=<key> ECHOPOINT_ORGANIZATION_ID=<org> \
  echopoint flows run --tag smoke -o json

GitHub Action

Run a smoke suite on every pull request

nanostack-dev/echopoint-cli@v1 wraps the same ephemeral execution in a single step. Point it at one flow-id, a list of flow-ids, or tags with match-mode any|all; choose the environment, pin a version-id, and tune parallel and poll-timeout (default 300 seconds).

Your API key is auto-masked in logs, and resolved secrets are never logged. The step's outputs hand downstream jobs the execution IDs, status, and results. Follow the GitHub Action reference for all inputs and outputs.

This example assumes you already have access to Echopoint, flows tagged smoke, and a staging environment whose API is reachable from the job. Save the API key and organization ID as the two named GitHub Actions secrets before running it.

A failed flow fails the job. Make this job a required status check in your repository if you want it to block merges. GitHub does not pass repository secrets to ordinary fork pull requests; see GitHub's secrets guidance before enabling tests for outside contributors.

.github/workflows/api-smoke-tests.ymlyaml

name: api-smoke-tests
on: [pull_request]

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: nanostack-dev/echopoint-cli@v1
        with:
          api-key: ${{ secrets.ECHOPOINT_API_KEY }}
          organization-id: ${{ secrets.ECHOPOINT_ORG_ID }}
          cli-version: v1.7.0
          tags: smoke
          environment: staging
          parallel: '3'

Action outputs

execution-id(s) Identifiers of the launched executions

status completed · failed · error

success Boolean — true when every flow passed

results-json Full results payload for downstream steps

CLI exit codes

0 All flows passed

1 A flow failed

2 Cancelled

3 Contract or API error

4 Poll timeout

--idempotency-key Deduplicates matching launch retries; a new CI attempt can run again

Scopes & secrets

Scoped keys and a hard secret boundary

Create an org-scoped API key with flows:execute to launch and claim the execution. Add flows:read if you select suites by tag. Progress and completion use a token scoped to that job; the API key does not need runner protocol permissions for these CI runs. See API key scopes.

The CLI launches an ephemeral execution, claims its job once, and runs the flow using its embedded engine. The claim delivers resolved inputs to your CI worker, including secrets the flow needs. Protect that worker and use a dedicated key: execution permission grants access to those inputs. The CLI keeps them out of its logs and GitHub summary.

Runners

Run where your API is reachable

By default each CI run is ephemeral: a one-shot runner inside your job, nothing persistent to babysit. When flows must run from inside your network, run the self-hosted echopoint-runner on your own infrastructure, with lease-based job claiming, heartbeats, and live runner status with load and heartbeat freshness in the app.

Either way you keep the same controls: --environment to pick a staging or prod overlay, --version-id to pin the exact published flow, and --parallel to fan out a CI suite.

A private API still needs a runner with network access to it. Run the Action on a CI host that can reach the target, or use a long-lived self-hosted Echopoint runner for launched flows. Both need outbound HTTPS to the Echopoint control plane; self-hosting a runner does not make execution fully offline. See testing APIs behind a VPN and the runner guide.

Ephemeral: flow snapshot + resolved inputs in, results out, process ends
Self-hosted: lease-based claiming, heartbeats, live load in the UI
Version pinning and environment selection on every launch

How it works here

Four steps to a merge gate

Create a ci key

Use a dedicated key with flows:execute. Add flows:read when selecting flows by tag.

Tag your suite

Tag flows "smoke" — lowercase, up to 32 tags per flow — to group them into suites.

Add one step

Drop in the GitHub Action, or call echopoint flows run --tag smoke from any CI.

Require the check

A failed flow fails the job. Configure it as a required status check to gate merges, then inspect failed assertions in the job summary.

Make --tag smoke your merge gate.

Join the waitlist for access. While you wait, review the Action setup and plan your first smoke suite. Free while in beta, no credit card.