docs/ci-api.md

Rama main · réplica de lectura del repositorio original.

# CI access through the self-hosted dashboard

Use the public HTTPS dashboard origin followed by `/api/v1`, for example
`https://hakopod.example.com:8443/api/v1`. CI supplies its own machine bearer key.
Browser cookies are not used. The Go API still validates key expiry, project,
environment, application restrictions and permissions on every request.

The dashboard forwards these machine API routes:

| Method | Route | Purpose |
| --- | --- | --- |
| GET | /applications | List applications with project/environment query parameters |
| GET | /applications/{id} | Fetch the current specification and revision |
| GET | /applications/{id}/provenance | Read accepted image-to-commit mappings |
| POST | /plan | Review an application or selected-service deployment |
| POST | /deployments | Accept the reviewed deployment |
| GET | /deployments/{id} | Poll deployment status |
| GET | /idempotency/{key} | Recover a deployment after an ambiguous connection failure |
| GET | /openapi.json | Inspect the API contract |

These routes are supported through the dashboard in alpha.16 and later.
Alpha.15 does not contain this forwarding fix. HTTP MCP has a separate route.

Use a short-lived scoped key with `deployments:read` and
`deployments:write` for deployment automation. Store it in CI's secret store.
The proxy preserves the request body, query scope and `Idempotency-Key`, and
returns canonical authorization, revision-conflict and rate-limit errors.
Only the listed methods and routes are forwarded; this is not an unrestricted
proxy for installation administration.

## GitHub Actions step

Use the [Hakopod deployment action](https://github.com/hakopod/deploy) to fetch the
current application, plan a selected-service change and submit it with a
revision check:

```yaml
- name: Deploy to Hakopod
  id: deploy
  uses: hakopod/deploy@v1
  with:
    api-url: ${{ vars.HAKOPOD_API_URL }}
    api-token: ${{ secrets.HAKOPOD_API_TOKEN }}
    application-id: ${{ vars.HAKOPOD_APPLICATION_ID }}
    services: '["api", "worker"]'
    env: '{"LOG_LEVEL":"info"}'
```

The action is maintained in [hakopod/deploy](https://github.com/hakopod/deploy)
and published on [GitHub Marketplace](https://github.com/marketplace/actions/deploy-to-hakopod).
Pin a full reviewed release commit SHA for production. The token needs the scoped
permissions above. The step waits for success by default, uses each
service's saved image unless an image digest is supplied, and supports individual
service images, environment patches and existing secret references. It needs no
checkout or CLI installation. The action guide covers concurrency, outputs,
timeouts and recovery after an ambiguous deployment response. Maintainers can
follow the [action release guide](https://github.com/hakopod/deploy/blob/main/RELEASING.md)
in that repository.

### API compatibility tests

This repository tests the released action against its real Go API handlers and
an isolated PostgreSQL database. CI checks out `hakopod/deploy` at a full commit
SHA; the action's source, unit tests and runner smoke test live in that repository.
When updating the supported action version, update the pinned checkout in
`.github/workflows/ci.yml` and run these compatibility tests.

To run them locally, check out the action and set `HAKOPOD_DEPLOY_ACTION_PATH` to
its absolute directory path. For the current `v1.0.0` release, from this
repository's root:

```sh
git clone https://github.com/hakopod/deploy.git .local/deploy-action
git -C .local/deploy-action checkout --detach 8b3a7e4927761e9dbc4128441b67a06993082183
export HAKOPOD_DEPLOY_ACTION_PATH="$PWD/.local/deploy-action"
go test ./internal/api -run '^TestGitHubAction' -count=1 -v
```

Set `HAKOPOD_TEST_DATABASE_URL` to a development PostgreSQL connection before
running the tests and install Node.js 24 (`HAKOPOD_ACTION_NODE` can select its
binary). When `HAKOPOD_DEPLOY_ACTION_PATH` is unset, local runs skip these tests
explicitly. An invalid configured action path fails the tests. These checks cover durable
deployment acceptance, authorization, revision conflicts and response recovery;
they do not exercise a Kubernetes rollout.

## Stop on a failed specification fetch

A 404 followed by “services not in the app spec” does not establish that the
services are missing. A script that continues after curl fails may be validating
an empty document or an error response.

Keep retrieval and validation as separate, fail-fast steps. For Bash:

```bash
set -euo pipefail
: "${HAKOPOD_ORIGIN:?Set the public HTTPS dashboard origin}"
: "${HAKOPOD_API_KEY:?Set a scoped machine key}"
: "${HAKOPOD_APP_ID:?Set the application ID}"

umask 077
app_file=$(mktemp)
trap 'rm -f "$app_file"' EXIT

curl --fail-with-body --silent --show-error \
  --connect-timeout 10 --max-time 40 \
  --header "Authorization: Bearer $HAKOPOD_API_KEY" \
  --output "$app_file" \
  "${HAKOPOD_ORIGIN%/}/api/v1/applications/$HAKOPOD_APP_ID"

jq -e '.spec.services | type == "object"' "$app_file" >/dev/null
jq -e --argjson selected '["setup","celery-beat","celery-worker","api"]' '
  .spec.services as $configured |
  ($selected - ($configured | keys)) as $missing |
  if ($missing | length) == 0 then true
  else error("services not in the Hakopod app spec: " + ($missing | join(", ")))
  end
' "$app_file" >/dev/null

# Continue with the reviewed plan/deployment workflow only after both checks pass.
```

Do not remove TLS verification, use browser session cookies in CI, or bypass the
public listener by exposing the internal API port. A deployment's acceptance is
not rollout success: poll the returned deployment ID until a terminal status.

See [the deployment workflow guide](https://hakopod.com/docs/ci-deployments/) for
selected-service payloads, revision handling and retries.