Publish private OpenAPI docs from GitHub Actions.

The publish job should consume the same OpenAPI file your build produces, not a separately maintained copy. Validate that generation succeeded and that the document includes the title, version, paths, and schemas consumers expect.

• Fail the workflow when generation or validation fails
• Publish only from the branch or environment that owns the reference
• Keep staging and production references on different slugs when they describe different contracts

Publish once from a trusted local environment, select the page audience, and verify the viewer URL. Later GitHub Actions runs can update the same slug without changing that URL.

npx @internalpage/cli publish ./openapi.yaml --slug specs/billing-api

Save the internalpage token as a repository, organization, or environment secret and expose it only to the publish step. GitHub notes that workflow secrets must be explicitly passed to an action or command before the workflow can use them.

• Use an environment secret when deployment approval or branch restrictions matter
• Do not print the token or place it inside the OpenAPI document
• Avoid granting the secret to untrusted pull-request workflows

A CI secret can be used by workflow code that receives it. Pin and review third-party actions, and keep the publish job small.

Install or invoke the CLI in the workflow, pass the token through its supported environment, and publish the generated file to the established slug. The JSON flag makes output easier to capture in logs and later automation.

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

A production API reference can use a GitHub environment with branch rules, required reviewers, and environment-scoped secrets. This separates routine schema checks from the step that changes the page teammates treat as current.

• Restrict publishing to the canonical branch or release workflow
• Require approval when API documentation changes are operationally sensitive
• Keep preview references on a different page and access policy

A successful upload does not prove the reference is useful. Open the viewer URL, confirm the version and representative endpoints, and test both authorized and unauthorized accounts when the access model changes.

• Show the API version or commit in info.version
• Check that schemas and examples still render
• Link the stable reference from runbooks and service ownership docs
• Rotate the CI token if workflow logs or configuration expose it