GitHub Action

Block CI on launch readiness. The PulseLight Action scans the current commit, waits for the verdict, and fails the step when blockers are present.

Early access. pulselight-io/scan-action is preparing for first publish; the bundled runtime (dist/index.js) and the marketplace listing land alongside the first tag. Track shipping at /changelog.

What it does

On every workflow run, the Action triggers a PulseLight scan on the current commit, polls until the scan completes, reads the verdict from the readiness API, and exits non-zero when the configured threshold is breached. Same exit-code contract as the internal pulselight pre-deploy CLI command — 0 ships, anything else blocks the merge.

Read-only: the Action never writes back to your repo or your PulseLight workspace. Auth is one Personal Access Token per repo, scoped by the user’s workspace memberships.

Quickstart

Drop a workflow into .github/workflows/launch-readiness.yml:

name: Launch readiness

on:
  pull_request:
  push:
    branches: [main]

jobs:
  pulselight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pulselight-io/scan-action@v1
        with:
          token: ${{ secrets.PULSELIGHT_TOKEN }}
          workspace-id: ws_…
          project-id: proj_…
          # Optional — default is "blockers"
          block-on: blockers

Get a token

Mint a Personal Access Token from Settings → API tokens → Create token. Copy the pul_… string and store it as PULSELIGHT_TOKEN in your GitHub repo under Settings → Secrets and variables → Actions.

Workspace and project IDs both live in the dashboard URL after you log in (app.pulselight.io/workspaces/ws_…/projects/proj_…) or on the same Settings → API tokens page.

Same token contract as the MCP server. If you already minted one for Cursor or Claude Code, reuse it — no separate token needed unless you want a different revocation handle. See /docs/mcp for the editor flow.

Inputs

token (required) — PulseLight Personal Access Token.
workspace-id (required) — PulseLight workspace UUID.
project-id (required) — PulseLight project UUID.
api-base (optional, default https://api.pulselight.io) — override only for self-hosted / staging.
block-on (optional, default blockers) — severity gate. See below.
timeout-minutes (optional, default 10) — maximum wait for the scan to complete.

Outputs

verdict — one of ready_to_launch, not_ready_yet, risky_but_shippable, needs_rescan, monitoring_only.
blocker-count / warning-count — counts on the scanned commit.
scan-url — dashboard link to the scan-detail page (use it to comment rich context onto the PR from a follow-up step).

Block-on policy

blockers (default) fails when the verdict is not_ready_yet or there is at least one open launch blocker. Same gate the internal pre-deploy CLI used.

warnings-and-up is stricter — blockers OR warnings fail the step. Recommended only for repos that age out warnings aggressively.

any is the strictest gate — any open finding fails. Use sparingly; catches issues like advisory-tier suggestions that don’t usually block launch.

needs_rescan always fails regardless of policy — the verdict says the data isn’t trustworthy.

Troubleshooting

The Action fails with 401. Token is wrong, expired, or revoked. Check Settings → API tokens — if missing, mint a new one and update the GitHub secret.

The Action times out. The scan didn’t complete within timeout-minutes. Check the dashboard for queue depth or scanner errors. If the scan completed but the Action still timed out, the API polling endpoint may be blocked — rerun the workflow.

Rate-limited (429). Per-token rate limits are 60 requests / minute on most endpoints. If you’re hitting this from many concurrent workflows, mint a second token for the second workflow — each token gets its own bucket.

What’s next

For the editor companion (same launch verdict, exposed to Cursor / Claude Code via MCP), see /docs/mcp. For the GitHub PR-comment integration that posts the verdict to every PR, see GitHub PR comments in the sidebar once it ships.