Skip to content

How-to: use bupha as a GitHub Action ​

uses: 9aia/bupha is a composite action at the bupha repo root — bash + curl/jq only, no build step and no bupha listener needed. It reads the forge's combined commit-status API, which is where bupha's watcher posts its verdicts ([status].context, default ci/bupha).

Typical use: a repo's own GHA workflow waits for — or reports — the bupha gate verdict on a sha, without checking out anything or reaching the bupha box.

Gate on the bupha verdict ​

yaml
permissions:
  contents: read
  statuses: read          # required for private repos

jobs:
  bupha-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: 9aia/bupha@main    # pin to a tag or SHA in production
        with:
          mode: wait
          timeout: "900"

mode: wait polls GET /repos/{owner}/{repo}/commits/{sha}/status, picks the latest entry matching context (default ci/bupha), and exits non-zero when the status reaches failure, error, or the timeout elapses — the step is a drop-in required check.

Report the verdict without failing ​

yaml
- uses: 9aia/bupha@main
  id: bupha
  with:
    mode: status            # one fetch, always exit 0
- run: echo "bupha: ${{ steps.bupha.outputs.state }} — ${{ steps.bupha.outputs.description }}"

Outputs:

outputvalues
statepending success failure error none timeout
descriptionthe status description bupha posted
target-urlstatus target_url (run/log link)

none means nothing was posted for that sha/context yet — usually the webhook hasn't landed or the repo isn't watched. In wait mode none is treated as not-terminal and keeps polling.

Inputs ​

inputdefaultnotes
modewaitstatus (one shot) or wait (poll to terminal)
sha${{ github.sha }}for pull_request, prefer github.event.pull_request.head.sha
contextci/buphamust match the bundle's [status].context
repo${{ github.repository }}owner/repo
token${{ github.token }}needs statuses: read on private repos
api-basehttps://api.github.comGHES override
timeout600seconds, wait mode; integer 0–86400
interval15seconds between polls; integer >= 1

Both knobs are validated up front (exit 2 on a bad value) — a non-numeric or out-of-range input fails fast instead of dying mid-poll. In wait mode a failed fetch or unparseable response is treated as transient and retried until the deadline; in status mode it exits 1 with a clean error.

What it does not do ​

There is no trigger mode. Firing a bupha run from GHA would mean a public, unauthenticated ingress — production webhook/forge ingress is peregrin-owned and the bupha webhook listener requires an HMAC signature (ADR-0007). To kick CI off, push to a watched ref, use the bundle's hooks register, or drive a peregrin campaign.

Manual test ​

No live GitHub needed — stub curl and exercise the script:

sh
mkdir /tmp/fake && cat > /tmp/fake/curl <<'EOF'
#!/usr/bin/env bash
cat <<'JSON'
{"state":"success","statuses":[
 {"context":"ci/bupha","state":"success","description":"ci passed",
  "target_url":"https://example/run/1","created_at":"2025-01-01T00:00:00Z"}]}
JSON
EOF
chmod +x /tmp/fake/curl
PATH=/tmp/fake:$PATH BUPHA_MODE=status BUPHA_SHA=abc BUPHA_REPO=o/r \
  GITHUB_OUTPUT=/tmp/out.txt \
  bash scripts/gha-status.sh && cat /tmp/out.txt