Spec0docsCLI 0.7.0
Platform

Import from GitHub

Import an OpenAPI spec straight from a GitHub repository — pick the repo and spec file, confirm ownership and governance, and Spec0 publishes it and checks every pull request against it.

If your spec already lives in a repository, you don't need the CLI to get it into Spec0. APIs → Import from GitHub walks through four steps and leaves you with a published API whose source of truth stays in git.

This is the same end state as spec0 push — the difference is that Spec0 keeps reading the branch afterwards, so merges publish new versions and pull requests get checked automatically.

Before you start

You need the Spec0 GitHub App installed on the organisation that owns the repository. If the repo you want isn't in the list, the picker links to the install flow.

1. Pick the repository

Step 1 of the GitHub import wizard, with a repository selected from a dropdown.
Only repositories the Spec0 GitHub App can see appear here. If yours is missing, install or extend the App from the link under the field rather than re-authorising your account.

2. Choose the spec file and branch

Spec0 auto-detects files named openapi.yaml, .yml or .json. Real repositories rarely stop there, so two escape hatches sit alongside the dropdown: Browse repository opens the file tree, and the path field takes anything else — docs/api.yaml, spec/service.yml — and detects it.

Step 2, showing the detected spec file, a source-branch field, a Browse repository button, and a manual spec-path field.
The source branch is the one thing worth pausing on: it becomes the API's source of truth. Merges to it publish new versions, and pull requests against it are what Spec0 checks.

3. Name it and assign a team

Step 3 sets the API name and the owning team. The name defaults to the spec's info.title, and the team decides who can publish and who is asked to review.

4. Review

The last step is a summary, and the part worth reading is the governance line — it shows the modes your org policy will apply to this API from the first publish onward.

Step 4 review screen listing API name, owning team, source, and the governance modes that will apply.
Governance here is your existing org policy, not something set during import. A gate showing BLOCK will reject a non-conforming publish immediately — including the first one.

Press Import API and Spec0 publishes the spec, wires up the environment, and starts checking pull requests that touch that file.

What happens afterwards

  • Merges publish. A merge to the source branch publishes a new version, tagged with the commit.
  • Pull requests are checked. Breaking-change and lint results are posted as GitHub check runs and mirrored on the API's Checks tab.
  • The API is read-only in the dashboard. It shows Managed from GitHub — publish through the repository, not the UI, so git stays the source of truth.

See also

  • APIs — what an API is on Spec0, and the rest of its lifecycle
  • Governance — the policy gates applied at publish
  • Versioning — how versions are assigned and breaking changes classified
Was this helpful?
Edit on GitHub

APIs

The registry — versioned OpenAPI specs owned by teams, governed at publish time, mocked, subscribed to.

Versioning

How Spec0 assigns and stores API versions — and the recommended policy for evolving an API without breaking consumers.

On this page

Before you start1. Pick the repository2. Choose the spec file and branch3. Name it and assign a team4. ReviewWhat happens afterwardsSee also