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 can use ReDoc, Swagger UI, or Scalar in read-only mode. ReDoc is the initial workspace default, and each page can follow that default or keep an override.

If you are still choosing the access and hosting model, start with the private OpenAPI docs overview. For narrower decisions, see protect Swagger UI with Google SSO, share API docs with clients and partners, and Redocly vs internalpage.

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. Publish from CI

Run publish with a stable slug. The first run creates the page, and later runs update the same page.

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

The viewer URL and renderer preference stay stable while the current spec is replaced. Renderer changes are made in workspace or page settings, independently of the CI publish command.

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.