API tests on every pull request, with one GitHub Action

A coding agent changes an endpoint. The code compiles, but does the checkout sequence still work? A useful pull-request check needs to exercise the API, compare the responses with explicit expectations, and give the agent and reviewer enough detail to investigate failures.

Echopoint’s API testing in CI runs your flows inside the CI job. The CLI includes a one-shot runner, publishes execution results back to Echopoint, and returns an exit code plus structured JSON. The same visual API flow can be reviewed in the canvas and run after each code change.

This guide assumes you already have Echopoint access. If you are evaluating the product, join the waitlist for access updates and use the public docs to review the setup.

Prepare the flow and target environment

Before adding the Action, you need:

• A flow with request steps and assertions, tagged smoke
• A staging environment whose variables point to the API you intend to test
• An organization API key with flows:execute and, for tag selection, flows:read
• GitHub secrets named ECHOPOINT_API_KEY and ECHOPOINT_ORG_ID
• A CI job that can reach the target API, with outbound HTTPS access to api.echopoint.dev

The example below tests the configured staging target. It does not automatically deploy the pull request or change the flow’s base URL to a preview URL. For branch-specific tests, deploy or start the service first, wait for it to be ready, and configure the flow to reach that target from the job.

If your starting point is an API specification, OpenAPI import and sync can maintain the request collection. You still define the flow sequence and assertions that express the behavior you want to check.

One Action, wired into your PR

name: API 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 }}
          tags: smoke
          environment: staging
          parallel: '3'

The Action validates that you passed exactly one selector: flow-id, flow-ids, or tags. It downloads the CLI, masks the API key in job logs, and runs echopoint flows run. The runner is embedded in the current CLI; a separate runner download is not needed. Use cli-version to pin a CLI release.

A non-zero exit makes the step fail. To make that check block a merge, configure it as a required status check in GitHub. Adding the Action alone does not change your repository’s merge rules.

GitHub normally withholds repository secrets from pull requests originating in forks. Plan a trusted test path for those contributions; do not expose the API key to untrusted pull-request code. See GitHub’s guidance on secrets.

The GitHub Action reference covers all inputs, outputs, and examples.

What runs inside the job

The current execution path is:

1. Launch: the CLI asks the control plane to create an ephemeral execution for the selected flow and environment
2. Claim: it receives the one-shot job, flow snapshot, resolved inputs, and a job token
3. Execute: the embedded runner sends requests from the CI job and evaluates assertions
4. Report: it uses the job token to send progress, heartbeats, and completion results to the control plane

The job can test only endpoints its network can reach. A GitHub-hosted runner does not gain VPN access by installing the Action. For a private API, use a job with suitable network access or a self-hosted Echopoint runner.

Outbound access to the Echopoint control plane is required even when the target API is local. Execution results leave the job and are stored in Echopoint’s run history. Review test data and recorded responses before testing sensitive systems; API-key masking is not a guarantee that arbitrary response data stays out of results.

Give the agent and reviewer usable results

The Action exposes these step outputs:

Its job summary shows per-flow results. When the job has jq, it also includes failed nodes and failed assertions with expected and actual values; otherwise it falls back to basic JSON output.

That gives a coding agent evidence to inspect rather than just a red check. For example, a flow can create an order, extract its ID, fetch it, and assert that its status is pending. If the assertion fails, review the recorded response, target environment, and expected value before changing code or weakening the assertion.

Select a smoke suite with tags

Tag the flows you want to run:

echopoint flows tag <flow-id> --add smoke

Then run the same suite from a terminal or another CI system:

echopoint flows run --tag smoke --environment staging --parallel 3 -o json

For API-key authentication outside the Action, provide ECHOPOINT_API_KEY and ECHOPOINT_ORGANIZATION_ID through your CI system’s secret configuration. The CLI setup guide covers installation and authentication.

Repeat --tag to select multiple tags. --match-mode any runs flows with any selected tag; --match-mode all requires every tag. Selection is capped at 50 flows, so narrow an over-broad suite. See the tag reference for organization and selection examples.

Timeouts, repeat launches, and exit codes

parallel controls concurrent flows, and poll-timeout bounds the wait for each execution. The Action’s default timeout is 300 seconds. For a single flow, version-id can pin the published version you reviewed.

In GitHub Actions, the CLI derives an idempotency key from the repository, workflow, job, run ID, and run attempt. Duplicate launches with the same key and scope reuse the execution, but rerunning a job with a new attempt generates a new key. An explicit --idempotency-key or ECHOPOINT_IDEMPOTENCY_KEY overrides the generated key. See the current CLI implementation.

Code 1 is a failed test execution, not proof that the API implementation is wrong. Test expectations, fixtures, dependencies, and runner behavior can also cause failures. Codes 3 and 4 tell you to investigate why execution could not complete normally.

Next steps

Start with one meaningful flow and a reachable test environment. Review the CI feature guide, build the assertions in the flow builder, and use the Action reference to wire it into your repository.

The CLI and Action source is public on GitHub. Echopoint is accepting waitlist requests; joining does not provide immediate app access.