# Manual Trigger Workflow (GitHub Action over VPN)

**Date:** 2026-06-03
**Status:** Approved (design)

## Goal

Let anyone with write access to this repo trigger the fix pipeline for a Jira ticket
without being on the VPN, via a manually dispatched GitHub Action that connects to the
corporate VPN and calls the private trigger endpoint.

## Background

The hu-agent debug API is only reachable through the private ALB of each environment
(`/hu-agent/*` path rule, see `infrastructure/env/dev/target_group.tf:27-41`). There is
no public ingress by design; the VPN/private network is the only barrier (the endpoint
itself has no auth). Today, triggering a run requires a human on the WireGuard VPN
running `curl` by hand.

Several repos in the org (e.g. `cx-hackathon-postgrest`, `humand-backend-infra`) already
connect GitHub Actions runners to the VPN using the shared composite action
`HumandDev/github-actions/.github/actions/wireguard-vpn@main` with the
`WIREGUARD_VPN_PRIVATE_KEY` secret.

## Design

One new workflow file: `.github/workflows/trigger.yml`. No changes to existing
workflows, app code, or infrastructure.

### Trigger

`workflow_dispatch` with two inputs:

| Input | Type | Values | Default | Notes |
|---|---|---|---|---|
| `environment` | choice | `dev`, `prd` | `dev` | Which hu-agent instance to hit |
| `issue_key` | string | — | (required) | Jira issue key, e.g. `SQCY-2848` |

No extra confirmation gate for `prd`: GitHub repo permissions (who can dispatch
workflows) are the access control, same as for the deploy workflows.

### Job steps

Single job (`ubuntu-24.04`), no checkout, no AWS credentials, no special permissions:

1. **Connect to VPN** — `HumandDev/github-actions/.github/actions/wireguard-vpn@main`
   with `WIREGUARD_VPN_PRIVATE_KEY: ${{ secrets.WIREGUARD_VPN_PRIVATE_KEY }}`.
2. **Resolve ALB hostname** — hardcoded env→DNS map in the workflow:
   - `dev` → `internal-private-services-1581368902.us-east-1.elb.amazonaws.com`
   - `prd` → `internal-private-services-1213332772.us-east-1.elb.amazonaws.com`
     (resolved via `PRD-RO` from the `private-services` ALB, same ARN as
     `infrastructure/env/prd/variables.tf`).
3. **Trigger pipeline** —
   `curl -sS -m 30 -X POST http://$ALB/hu-agent/api/pipeline/trigger` with JSON body
   `{"issueKey": "<input>"}`, capturing HTTP status and response body separately.
4. **Report** — append environment, issue key, HTTP status, and response body to
   `$GITHUB_STEP_SUMMARY`. Exit non-zero (failing the run) unless the status is `202`.

### Error handling

The endpoint already validates everything (`src/server/routes/debug.ts:1858-1883`):
`400` for a missing/invalid `issueKey`, `500` with an error message for downstream
failures (e.g. ticket not found in Jira). The workflow only distinguishes `202`
(success) from everything else (failure, with the response body surfaced in the
summary). VPN connection failures fail at step 1 with the shared action's own error.

The run is **fire-and-forget**: a `202` means the job was enqueued, not that the fix
succeeded. The actual outcome is observed where it already is today: Slack
notifications, Datadog metrics (`hu_agent.fix.outcome`), and the resulting PR.

## Non-goals

- Generic debug-API runner (arbitrary method/path/body). Only the trigger endpoint.
- Polling for job completion. The job can take up to 50 minutes and there is no
  per-issue status endpoint; adding one is out of scope.
- Runtime ALB discovery via OIDC. Hardcoded DNS keeps the workflow free of AWS auth;
  if an ALB is ever recreated, updating one line is the accepted cost.
- Any change to the endpoint itself (auth, validation, response shape).

## Risks

- **Secret availability:** `WIREGUARD_VPN_PRIVATE_KEY` appears to be an org-level
  secret. If its visibility is restricted to selected repos, `hu-agent` must be added
  to the allowed list before the workflow can run. Verify during implementation; the
  fix is a GitHub settings change, not code.
- **Stale ALB DNS:** accepted trade-off (see Non-goals).
- **prd triggers real writes:** a prd dispatch transitions the Jira card, comments, and
  opens a real PR — same blast radius as assigning the card to the bot. Dispatch access
  equals repo write access, which is the same trust level as merging code.

## Testing

Manual dispatch against `dev` with a disposable card (e.g. reuse `SQCY-2847`):

1. Run the workflow with `environment=dev`, `issue_key=SQCY-2847`.
2. Expect a green run with `202` and `{"accepted":true,...}` in the summary.
3. Confirm the job appears in dev logs/metrics (`hu_agent.jobs.enqueued`, env:dev).
4. Negative case: dispatch with a bogus key (e.g. `SQCY-99999`) and expect a red run
   with the Jira error in the summary.