Skip to content
Echopoint Echopoint Docs

GitHub Action

nanostack-dev/echopoint-cli@v1 runs flows ephemerally inside your workflow job: the CLI launches an execution, claims its one-shot job, and runs the flow with its embedded engine on the CI worker. A per-job token is used to report progress, renew the lease, and publish results. No separate runner binary is needed.

- uses: nanostack-dev/echopoint-cli@v1
  with:
    api-key: ${{ secrets.ECHOPOINT_API_KEY }}
    organization-id: ${{ secrets.ECHOPOINT_ORG_ID }}
    tags: smoke
    parallel: '3'

Inputs

Section titled “Inputs”
InputRequiredDefaultPurpose
api-keyyes—Org API key (store as a secret)
organization-idyes—Organization ID
flow-idone of—Run a single flow
flow-idsone of—Run multiple flows
tagsone of—Run every flow matching the tags
match-modenoanyTag matching: any or all
environmentno—Environment key resolved at launch
version-idno—Pin a published flow version
api-urlno—Alternate API base URL
cli-versionno—Pin a CLI release
poll-timeoutno300Seconds to wait for completion
parallelno1Flows to run concurrently

Exactly one of flow-id, flow-ids, or tags selects what runs.

Outputs

Section titled “Outputs”
OutputTypeMeaning
execution-id / execution-idsstringExecution ID(s) of the launched run(s)
statusstringcompleted, failed, or error
successstring'true' when every flow passed
results-jsonstringFull per-flow results as JSON

Required scopes

Section titled “Required scopes”

The API key needs flows:execute to launch and claim the one-shot job. Add flows:read when selecting flows with tags. Progress, heartbeats, and completion use the job token; runner:claim and runner:complete are not required on this API key. See API keys & permissions.

The action masks the API key in logs. The claim delivers resolved environment values, including referenced secrets, to your CI worker. Execution permission grants that access, so use a dedicated key and a trusted worker. The CLI does not write those inputs to logs, step outputs, or the GitHub summary.

Before your first run

Section titled “Before your first run”

You need access to Echopoint, a flow or tagged suite, and the two GitHub Actions secrets used below. Choose an Echopoint environment whose API is reachable from the CI job. The worker also needs outbound access to the Echopoint API; the Action needs access to GitHub Releases to download the CLI.

These examples target the current Action interface. Set cli-version: v2.0.2 to pin the CLI release verified for this guide. Repository secrets are not available to ordinary fork pull-request runs; review GitHub’s secrets guidance before handling outside contributions. A failed flow fails the job; make the job a required status check if it should prevent merges.

Example workflows

Section titled “Example workflows”

Single flow on every push

Section titled “Single flow on every push”
name: checkout-smoke
on: [push]
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 }}
          flow-id: ${{ vars.CHECKOUT_SMOKE_FLOW_ID }}

Tag suite, three flows in parallel

Section titled “Tag suite, three flows in parallel”
name: smoke-suite
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
          match-mode: any
          parallel: '3'

Environment and version pinned

Section titled “Environment and version pinned”

Run one flow against staging, pinned to a published version of that same flow so the test definition does not drift while a release is in flight:

name: staging-gate
on:
  push:
    branches: [main]
jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: nanostack-dev/echopoint-cli@v1
        with:
          api-key: ${{ secrets.ECHOPOINT_API_KEY }}
          organization-id: ${{ secrets.ECHOPOINT_ORG_ID }}
          flow-id: ${{ vars.CHECKOUT_SMOKE_FLOW_ID }}
          environment: staging
          version-id: ${{ vars.CHECKOUT_SMOKE_VERSION_ID }}
          poll-timeout: '600'

For multiple pinned flows, use a separate Action step or a matrix entry for each flow/version pair. version-id is one flow’s published version, not a shared suite version; do not apply it to a flow-ids list or a tag suite.

Consume the outputs

Section titled “Consume the outputs”

Give the step an id and branch on success or parse results-json:

jobs:
  smoke:
    runs-on: ubuntu-latest
    steps:
      - uses: nanostack-dev/echopoint-cli@v1
        id: echopoint
        with:
          api-key: ${{ secrets.ECHOPOINT_API_KEY }}
          organization-id: ${{ secrets.ECHOPOINT_ORG_ID }}
          tags: smoke
      - name: Report results
        if: always()
        run: |
          echo "status=${{ steps.echopoint.outputs.status }}"
          echo '${{ steps.echopoint.outputs.results-json }}' | jq .
      - name: Block deploy on failure
        if: steps.echopoint.outputs.success != 'true'
        run: exit 1

Next steps

Section titled “Next steps”