Onboarding a Microservice

Onboarding connects a microservice repository to the API References. It is done once per repository, from inside the repo, with the microservice-api-docs plugin.

Before You Start

Install the plugin from kalt-ai-plugin-marketplace and run the onboarding skill from the root of the service repo:

/plugin install microservice-api-docs@kalt-ai-plugins
/microservice-api-docs:onboard

The skill asks for two values it cannot find in the code. Have them ready:

Platform — kaltura.ai or kaltura.com
Host prefix — everything before the region in the public URL. For example, ovp-agentic-api is served at https://api.avatar.qa.kaltura.ai, so its host prefix is api.avatar.

You also need push access to platform-content-registry to register the service.

What Onboarding Does

1. Checks the repo

The skill checks that the repo has OpenAPI specs in docs/specs/ and finds the image-tag keys that the CD job updates in the staging and production values files. It stops on the first failed check and explains how to fix it.

2. Registers the service in the registry

Each repository registers itself under microservices/servers/{domain}/ in platform-content-registry. The domain comes from the repository name with the ovp- prefix removed — it is never chosen by hand:

Repository	Registry domain
`ovp-agentic-api`	`agentic-api`
`ovp-genie`	`genie`

The registry manifest lists the public base URL for each staging and production region. The skill shows you the full list of URLs and waits for your approval before it pushes the manifest.

3. Creates two workflows

Workflow	Runs when
`.github/workflows/docs-staging.yaml`	A new image is deployed to staging (nvq2)
`.github/workflows/docs-prod.yaml`	A new image is deployed to production. Created disabled until production publishing is approved.

The workflows are committed on a new docs-onboarding-<sha> branch, never on your current branch, and the skill asks before it pushes and opens the PR. What they do is described in Staging & Production.

4. Adds the service to the API References

The skill asks which API References domain the service belongs to — for example, Agentic API. A dedicated skill then adds the service to that domain in the API References manifest of docs-kaltura-com and opens a PR there for review.

Onboarding does not improve quality. It publishes the specs as they are. Improving them is a separate step — see OpenAPI Spec Quality.

Review and Approval

Each API References domain has curated pages written by developers and tech writers. When the docs PR is opened, the domain is enriched with these pages, and the curated pages go to review together with the generated reference.

Approval is needed only once. After the PR is merged, new spec versions are published on every deploy without another review.

Already Onboarded?

Running /microservice-api-docs:onboard again on an onboarded repo verifies the setup instead of changing it. It compares the workflows with the current templates, checks the registry manifest, and reports each check as ✓ or ✗. It changes nothing without your approval.