Phase 2 — Add Guard to an existing deploy pipeline

You already have test → deploy-staging green. This adds guard-checkpoint-staging after deploy. Your existing ci.yml is not replaced.

0. Phase 1 must be green first

Pipeline today:

push main → test → deploy-staging

GitHub → Settings → Secrets and variables → Actions:

Type	Name	Example
Variable	STAGING_DEPLOY_PLATFORM	render
Variable	STAGING_API_URL	https://sample-deploy-api.onrender.com
Secret	STAGING_DEPLOY_HOOK	Render deploy hook URL

Important: STAGING_API_URL must be a Variable, not a Secret. If it is a Secret, deploy fails with curl: No host part in the URL.

Demo repo: sample-deploy-api

1. Prepare Guard session endpoints (ProxyHawk Mac app)

1. Open ProxyHawk → left sidebar Guard (shield icon).
2. Select your Guard session (or create one).
3. Choose one endpoint source:
   • Record API calls from live traffic, e.g. GET https://your-api.onrender.com/api/v1/profile
   • Import from OpenAPI/Swagger JSON
   • Import from Postman collection

After import/recording, you still must complete Steps 2–3 (routing + deploy checkpoint) before CI mapping works.

2. Session routing — Environment = staging

Do this before saving deploy checkpoint. If left empty, the app defaults to dev and Guard CI will not find your mapping.

1. On the Guard session page, open Session routing.
2. In Environment label, type: staging
3. Click Save (toast: “Saved alert environment: staging”).

This must match your CI job: environment: staging (Step 5).

You can edit this later if your environment label changes.

3. Save deploy checkpoint (Mac app)

Open Deploy checkpoint (CI) and fill:

Field	Example
Repository owner	prabagaranganesan
Repository name	sample-deploy-api
Deploy host override (optional)	https://sample-deploy-api.onrender.com

Confirm gray text: Environment: staging (from Session routing above)

Click Save deploy checkpoint (teal button).

If save fails with Guard session belongs to another account, that local session UUID is owned by a different ProxyHawk account on the backend. Sign in with the original account or create a new Guard session under the current account and save again.

You can edit deploy checkpoint mapping later (owner/repo/environment/host override).

4. Install Guard CI files (includes check.yml)

From your backend repo root — one command installs Guard CI workflow files. Do this before Step 5 (the Guard job calls check.yml).

curl -fsSL https://proxyhawk.io/guard-ci/install.sh | bash

Installs:

• check.yml — required reusable Guard job (proxyhawk-guard check)
• deploy.yml — optional deploy + health verify (fresh pipeline)
• deploy-wait.yml — alias (skip if Phase 1 already has deploy-wait)
• guard-post-backend-deploy.yml — legacy wrapper
• guard-deploy-pr-check.yml — legacy PR checkpoint

Commit and push:

git add .github/workflows/
git commit -m "Add ProxyHawk Guard CI"
git push

Alternative: Mac app → Guard Alerts → Export GitHub CI pack to repo… (same workflow files).

5. Wire your existing pipeline workflow

Edit your workflow file — e.g. .github/workflows/ci.yml or backend-ci.yml. Do not replace the whole file.

Naming: your pipeline filename and job IDs can be anything. Only needs: must reference your deploy job id. Keep the downloaded Guard workflow filenames (guard-post-backend-deploy.yml, etc.) — your job calls them via uses:.

5a. Permissions (top-level, alongside jobs:):

permissions:
  id-token: write
  contents: read

jobs:
  # your existing jobs…

pull-requests: write is optional and only needed if you want Guard to upsert PR comments.

5b. Guard job after your deploy job (same branch / if: as deploy). Requires check.yml from Step 4:

  guard-checkpoint-staging:         # job id — your choice
    needs: deploy-staging           # must match YOUR deploy job id
    if: success()
    uses: ./.github/workflows/check.yml
    with:
      environment: staging          # must match Mac app Session routing (Step 2)
      api_url: ${{ vars.STAGING_API_URL }}
      commit_sha: ${{ github.sha }}
      wait_for_deploy: true
      health_path: /api/health      # use /health if your API differs
    secrets:
      PROXYHAWK_API_EMAIL: ${{ secrets.PROXYHAWK_API_EMAIL }}
      PROXYHAWK_API_PASSWORD: ${{ secrets.PROXYHAWK_API_PASSWORD }}

Legacy alternative: uses: ./.github/workflows/guard-post-backend-deploy.yml with secrets: inherit.

This job must be inside top-level jobs:, right after your deploy job. Minimal shape:

jobs:
  deploy-staging:                   # your deploy job id
    # ... deploy config ...

  guard-checkpoint-staging:
    needs: deploy-staging
    uses: ./.github/workflows/check.yml
    with:
      environment: staging
      api_url: ${{ vars.STAGING_API_URL }}
      commit_sha: ${{ github.sha }}
      wait_for_deploy: true
    secrets:
      PROXYHAWK_API_EMAIL: ${{ secrets.PROXYHAWK_API_EMAIL }}
      PROXYHAWK_API_PASSWORD: ${{ secrets.PROXYHAWK_API_PASSWORD }}

Commit and push.

6. GitHub secrets (Phase 2 only)

Keep all Phase 1 variables/secrets. Add:

Type	Name
Secret	PROXYHAWK_API_EMAIL
Secret	PROXYHAWK_API_PASSWORD
Secret / Variable (optional)	PROXYHAWK_GUARD_RUNNER_URL (override runner binary URL)
Secret (optional)	PROXYHAWK_GUARD_RUNNER_TOKEN (Bearer token when override URL requires auth)

Same ProxyHawk account that saved the deploy checkpoint in Step 3.

7. Push and verify

git push origin main

Expected:

test → deploy-staging → guard-checkpoint-staging

Check ProxyHawk Guard dashboard for a new run.

Health check:

curl -sS https://your-api.onrender.com/api/health | python3 -m json.tool

Troubleshooting

Symptom	Fix
curl: No host part in the URL	STAGING_API_URL → GitHub Variable, not Secret
no active mapping	Step 3 deploy checkpoint; Step 2 must be staging not empty/dev
Guard session belongs to another account (Mac app save)	Create a new Guard session under the current account, then save deploy checkpoint again
SAVE_DEPLOY_CHECKPOINT (preflight)	Complete Steps 2–3 before bootstrap
Missing guard-runner binary	Backend runner hosting/signing not configured, or set PROXYHAWK_GUARD_RUNNER_URL override
Failed to obtain signed runner URL	Ask your ProxyHawk operator to configure backend runner signing/binary hosting, or set PROXYHAWK_GUARD_RUNNER_URL override
Curl download-url works locally but CI still shows generic error	Push latest .github/workflows/guard-deploy-pr-check.yml to customer repo; older copies hide backend response body
Guard job skipped	Step 5 — add Guard job; needs: must match your deploy job id
Guard login failed	Step 6 — PROXYHAWK_API_EMAIL / PASSWORD

← Guard CI overview · Download CI files