# NotiBuddy Setup Guide — GitHub Actions

> Pause GitHub Actions deploys, Terraform applies, or releases until you verify and sign an end-to-end encrypted approval on your iPhone.
> Human-readable page: https://notibuddy.app/github-actions
> Full CLI, MCP & protocol reference: https://notibuddy.app/setup.md

## 1. Prerequisites & package verification

- **iOS/iPadOS app:** NotiBuddy (iOS 17+ / watchOS 10+ companion included).
- **Computer client:** `notibuddy` **0.4.0** (use `notibuddy@^0.4.0` with `npx` on Node.js 20+, or `brew install yourbit-network/tap/notibuddy`).
- **Publisher:** Yourbit, LLC ([npm](https://www.npmjs.com/package/notibuddy) · [GitHub](https://github.com/yourbit-network/notibuddy)). Do not substitute similarly named packages or invent pairing credentials.
- Verify the CLI runs before pairing:

```bash
npx -y notibuddy@^0.4.0 --help
```

## 2. Pair a dedicated CI sender key (local one-time step)

Do **not** reuse a personal laptop sender key for CI. Pair a dedicated sender key so it displays cleanly as **GitHub Actions** on the iPhone Face ID prompt and can be audited or revoked independently in **Connect**:

1. Ask the user to open **NotiBuddy** on iPhone → **Connect → Add** → **Create setup code → Share Setup** (valid for 10 minutes; keep the app open and online).
2. **Never ask the user to paste the `nbpair1.` code into chat.** Have the user run the pairing command in their own Terminal with a dedicated alias and label:

```bash
pbpaste | npx -y notibuddy@^0.4.0 pair --to ci --label "GitHub Actions"
npx -y notibuddy@^0.4.0 doctor --to ci
```

3. Instruct the user to copy the **entire JSON contents** of `~/.notibuddy/destinations/ci.json` into a GitHub Actions Secret named `NOTIBUDDY_CI_DESTINATION` — preferably scoped to a **branch-protected GitHub Environment** (e.g. `environment: production`) rather than a repo-wide secret.
4. **Important nuance:** After saving the secret in GitHub, the user may optionally remove the local copy (`rm ~/.notibuddy/destinations/ci.json` or `nb unpair --to ci`) so it does not sit unused on their laptop — **but they MUST NOT tap Disconnect on their iPhone**, because disconnecting on iPhone immediately revokes the key stored in GitHub Secrets too.
5. Never commit `ci.json`, print it in CI logs, or enable `set -x` in a step that holds `NOTIBUDDY_DEST_JSON`.

## 3. Configure GitHub Actions

**Target:** `.github/workflows/deploy.yml`

Pair a dedicated CI sender once locally, store its destination JSON in a protected GitHub Environment secret (NOTIBUDDY_CI_DESTINATION), then add this fail-closed Face ID gate:

```yaml
- name: Set up Node.js
  uses: actions/setup-node@v4
  with:
    node-version: '20'

- name: Request Face ID deploy approval
  shell: bash
  timeout-minutes: 15
  env:
    NOTIBUDDY_DEST_JSON: ${{ secrets.NOTIBUDDY_CI_DESTINATION }}
    APPROVE_OPTION: Approve
    DECLINE_OPTION: Reject
    TIMEOUT_SECONDS: '600'
    REF_NAME: ${{ github.ref_name }}
    COMMIT_SHA: ${{ github.sha }}
    REPO_NAME: ${{ github.repository }}
    ACTOR: ${{ github.actor }}
    RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
  run: |
    set -euo pipefail
    if [ -z "$NOTIBUDDY_DEST_JSON" ]; then
      echo "::error::Missing NOTIBUDDY_CI_DESTINATION secret."
      exit 1
    fi

    umask 077
    export NOTIBUDDY_HOME="${RUNNER_TEMP:-/tmp}/notibuddy-$$"
    NB_PREFIX="${RUNNER_TEMP:-/tmp}/notibuddy-cli-$$"
    trap 'rm -rf "$NOTIBUDDY_HOME" "$NB_PREFIX"' EXIT

    mkdir -p "$NOTIBUDDY_HOME/destinations" "$NB_PREFIX"
    printf '%s' "$NOTIBUDDY_DEST_JSON" > "$NOTIBUDDY_HOME/destinations/ci.json"
    npm --prefix "$NB_PREFIX" install --no-save --silent notibuddy@^0.4.0 >/dev/null

    "$NB_PREFIX/node_modules/.bin/nb" gate "Deploy ${REF_NAME}?" \
      --to ci \
      --sender "GitHub Actions" \
      --message "${REPO_NAME} · ${COMMIT_SHA:0:7} by ${ACTOR} · ${RUN_URL}" \
      --approve "${APPROVE_OPTION}" \
      --reject "${DECLINE_OPTION}" \
      --requires-auth \
      --timeout "${TIMEOUT_SECONDS}"
```

### Optional: one-way CI failure or release alert (zero wait time)

Use nb notify without --options to fire an instant encrypted notification when a workflow fails or finishes deploying:

```yaml
- name: Notify iPhone on workflow failure
  if: failure()
  shell: bash
  env:
    NOTIBUDDY_DEST_JSON: ${{ secrets.NOTIBUDDY_CI_DESTINATION }}
    REF_NAME: ${{ github.ref_name }}
    REPO_NAME: ${{ github.repository }}
    RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
  run: |
    set -euo pipefail
    umask 077
    export NOTIBUDDY_HOME="${RUNNER_TEMP:-/tmp}/notibuddy-$$"
    NB_PREFIX="${RUNNER_TEMP:-/tmp}/notibuddy-cli-$$"
    trap 'rm -rf "$NOTIBUDDY_HOME" "$NB_PREFIX"' EXIT
    mkdir -p "$NOTIBUDDY_HOME/destinations" "$NB_PREFIX"
    printf '%s' "$NOTIBUDDY_DEST_JSON" > "$NOTIBUDDY_HOME/destinations/ci.json"
    npm --prefix "$NB_PREFIX" install --no-save --silent notibuddy@^0.4.0 >/dev/null
    "$NB_PREFIX/node_modules/.bin/nb" notify "CI failed on ${REF_NAME}" \
      --to ci \
      --sender "GitHub Actions" \
      --message "${REPO_NAME} · ${RUN_URL}"
```

Preserve all existing servers, workflows, or settings when editing configuration files. Always configure NotiBuddy as a **local stdio MCP server or local CLI** — never point an MCP client at `https://notibuddy.app` as a remote MCP server.

## 4. Critical GitHub Actions engineering & security nuances

Read every item below before editing the user's `.github/workflows/*.yml`:

- **Use `nb gate` (not `nb notify`) for approval steps:** `nb notify` exits `0` even on Reject, `pending`, or `expired`. `nb gate` loops internally across 55-second relay wait windows on **one signed request ID** up to `--timeout` (default `600`s; max `10800`s / 3 hours), prints structured JSON to `stdout`, and exits fail-closed: `0` approved (matching `--approve` and `authenticated: true` when `--requires-auth` is set), `2` rejected/unauthenticated, `3` expired, `1` operational/config error (pairing, network, quota `402`).
- **`--requires-auth` + `--reject`:** Passing `--requires-auth` forces Face ID / Touch ID / passcode / unlocked Watch before approving and rejects any unsigned/unauthenticated reply with exit code `2`. The `--reject` button always skips biometrics so you can reject immediately.
- **Always bound runner time:** Set `timeout-minutes: 15` on the approval step (slightly above `TIMEOUT_SECONDS`) so a forgotten deploy or relay outage never burns hours of GitHub Actions runner minutes.
- **Install once into `$RUNNER_TEMP`:** Installing `notibuddy@^0.4.0` once via `npm --prefix "$NB_PREFIX" install --no-save --silent notibuddy@^0.4.0 >/dev/null` avoids repeated `npx` overhead and keeps `stdout` clean JSON. Always include `actions/setup-node@v4` (`node-version: '20'`) and `shell: bash` on `ubuntu-latest` or `macos-latest`.
- **Secret isolation & cleanup:** Always set `umask 077`, write `ci.json` to `NOTIBUDDY_HOME="${RUNNER_TEMP:-/tmp}/notibuddy-$$"` (never `~/.notibuddy`, which persists on self-hosted runners), and remove both `$NOTIBUDDY_HOME` and `$NB_PREFIX` in `trap ... EXIT`.
- **Prevent GitHub Actions shell injection:** Never interpolate `${{ github.ref_name }}`, `${{ github.event.head_commit.message }}`, or PR titles directly inside `run:`. Always pass them through `env:` and reference quoted shell variables (`"${REF_NAME}"`).
- **Protect secrets from fork PRs:** Never expose `NOTIBUDDY_CI_DESTINATION` to `pull_request_target` workflows that check out untrusted PR code. Restrict the deploy job to protected branches/tags or a protected GitHub Environment (`environment: production`).
- **Place approval after CI tests & serialize deploys:** Put the approval step in the deploy job (after build/test jobs pass, so you are never paged for a failing build) and consider a GitHub Actions `concurrency` group (`cancel-in-progress: false`) so overlapping deploys queue cleanly.
- **Optional diff review (`--diff`) & Custom Screens (`--screen`):** To review a Terraform plan or SQL migration diff on iPhone, write `{ "filename": "plan.tf", "language": "hcl", "original": "...", "modified": "..." }` to `$RUNNER_TEMP/diff.json` and call `nb gate "Apply plan?" --to ci --diff "$RUNNER_TEMP/diff.json" --requires-auth --timeout 600`. Note that `--diff` cannot be combined with `--approve`/`--reject`; `nb gate` automatically verifies the lowercase `"approve"` reply action ID (UI label **Apply**; decline ID `"reject"`, label **Discard**). For rich release dashboards (KPI strips, canary status alerts, checklists, and Face ID actions), use `nb notify "Promote ${REF_NAME}" --to ci --screen "$RUNNER_TEMP/screen.json" --wait 55` (and optionally pre-register custom templates with `nb screen register <file> [--strict]`).
- **Credential rotation & Free tier:** `notibuddy` 0.4.0 automatically recovers from `409 CREDENTIAL_ROTATED` using the sender signing key inside `ci.json`. Free allows 5 requests per rolling 24 hours (each new notification or approval counts as 1; internal wait windows do not count); teams deploying many times daily should use Pro.

## 5. Recommended rule — Security note for CI secrets

> Give GitHub Actions its own dedicated sender keypair (separate from your laptop) and pair it to a dedicated GitHub Environment with branch protection rules. Revoking it in Connect on iPhone takes one tap.

## 6. Verify both directions

Run a round-trip test with the paired alias (`ci`):

```bash
npx -y notibuddy@^0.4.0 doctor --to ci
npx -y notibuddy@^0.4.0 gate "Connection check" --to ci --message "Tap OK to confirm two-way replies." --approve "OK" --reject "Cancel" --timeout 120
```

Confirm setup only after receiving a verified signed reply from the phone. After saving `ci.json` to `NOTIBUDDY_CI_DESTINATION`, trigger a test run on a non-production branch or `workflow_dispatch` and verify both **Reject** (exits 2, blocks deploy) and **Approve with Face ID** (exits 0, allows deploy).

## 7. Tool contract & hard rules

- `notibuddy_notify` (`nb notify`): One-way encrypted notification by default; pass `options`, `input_placeholder`, `fields`, `diff`, `screen`, or `requires_auth: true` for interactive signed replies, or `resume_id` to poll an existing request. Ordinary requests allow up to **10,800 seconds (3 hours)**; `wait_seconds` / `--wait` is a separate poll budget (max 55s).
- **Custom Screens (0.4.0+):** Pass `screen: { templateId, labels, data }` (8 built-in layouts) or `screen: { template }` (12 native blocks: `vstack`, `card`, `divider`, `heading`, `text`, `badge`, `alert`, `kpiStrip`, `keyValueList`, `checklist`, `diffViewer`, `formField`, plus `actions` with optional Face ID) to `notibuddy_notify` or `nb notify --screen <json-file>` (or pre-register with `nb screen register <file> [--strict]`). The server validates and caches only the content-free layout template for up to 30 days while all text, metrics, diffs, and replies remain end-to-end encrypted.
- `nb gate`: Fail-closed CLI gate for scripts and CI/CD (exits `0` approved, `2` rejected/unauthenticated, `3` expired, `1` operational error).
- `nb hook claude PermissionRequest`: Native Claude Code permission hook with 10s local grace period, hidden Lock Screen previews by default, opt-in `--requires-auth`, rolling hourly cap, and silent pass-through on non-decision outcomes. Requires a local `nb` install (never `npx`).
- `notibuddy_activity`: Start, update, end, or poll Lock Screen / Dynamic Island / Apple Watch progress and timers (1-hour lifetime; the agent must poll and act on pause/resume/cancel controls).
- `notibuddy_files`: `action: "list"` and `action: "receive"` (`id` required) to download encrypted phone uploads up to 10 MB under `~/.notibuddy/inbox/`. Never auto-execute received files.
- **Fail closed:** Never treat a timeout, expiry, error, or silence as approval.
- **Keep sessions awake:** The sending host or workflow must stay running to receive replies; NotiBuddy cannot wake a sleeping machine or restart an ended session.
- **Full specification:** https://notibuddy.app/setup.md
