Publish OpenAPI Docs from CI

Use internalpage when CI already generates an OpenAPI YAML or JSON file and your team needs a private browser link for review.

OpenAPI pages are rendered as read-only Redoc references.

1. Generate the spec

Create the OpenAPI file in your CI job.

make openapi

The source file can be .yaml, .yml, or .json. internalpage validates that the upload is an OpenAPI 3.x or Swagger 2.0 document with info.title.

2. Store an internalpage token

Create a personal API token in internalpage, then store it in your CI secret store as INTERNALPAGE_TOKEN.

Use direct environment variables only in CI or short-lived shells.

3. Create the first page

Run this once from a trusted environment and save the returned page ID.

IP_TOKEN="${INTERNALPAGE_TOKEN}" \
npx @internalpage/cli pages create ./openapi.yaml --slug billing-api

4. Update from CI

Use the saved page ID for recurring CI updates.

IP_TOKEN="${INTERNALPAGE_TOKEN}" \
npx @internalpage/cli pages update pg_xxx ./openapi.yaml

The viewer URL stays stable while the current version is replaced.

Good fits

• internal service API docs
• pre-release partner API specs
• staging API references
• generated docs for QA and PM review

Boundaries

internalpage is intentionally a private read-only viewer for OpenAPI specs. It does not run API requests, collect API tokens, create mock servers, or generate SDKs.