OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

Private packages

Access ContractSpec on GitHub Packages

Scoped ContractSpec packages are distributed through GitHub Packages and are private by default. The unscoped contractspec CLI compatibility package remains on npmjs until a separate scoped CLI migration is planned. Ask for access first, then configure local and CI registry credentials before installing private packages or running actions that install private packages.

1) Request access

Contact the ContractSpec team with your GitHub username or organization, the consuming repository, and whether access is for a person, CI bot, or GitHub App. Consumers normally need read-only package access; release automation is the only path that needs package write access.

2) Configure local registry auth

Export a token that can read the private packages. Keep real token values out of source control, examples, issue comments, and logs.

export GITHUB_PACKAGES_TOKEN=<token-with-read-package-access>

.npmrc

@contractspec:registry=https://npm.pkg.github.com
@lssm-tech:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}

bunfig.toml

[install.scopes]
"@contractspec" = { token = "$GITHUB_PACKAGES_TOKEN", url = "https://npm.pkg.github.com" }
"@lssm-tech" = { token = "$GITHUB_PACKAGES_TOKEN", url = "https://npm.pkg.github.com" }

3) Use ContractSpec GitHub Actions

External repositories can still call ContractSpec actions. Pass a token with private package read access when the action needs to install or execute ContractSpec packages. The caller repository's github.token works only after that repository has package access.

contractspec-action.yml

permissions:
  contents: read
  packages: read

jobs:
  contractspec:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: lssm-tech/contractspec/packages/apps/action-pr@main
        with:
          github-packages-token: ${{ secrets.CONTRACTSPEC_PACKAGES_TOKEN }}
          generate-command: 'bun contractspec generate'

Maintainer CI/CD boundary

Maintainer workflows publish to https://npm.pkg.github.com, request packages: write, and prefer a dedicated GITHUB_PACKAGES_TOKEN secret. Same-repository automation can fall back to github.token, but cross-repository consumers should use an explicitly granted secret.

Back to installation Next: CI gating

OSS docsstartStart with OSS. Adopt Studio when you want the operating layer.

Hello world

Define a first operation, generate the surface, and verify the end-to-end loop.

Why ContractSpec

Keep educational and comparison content reachable without letting it define the primary OSS learning path.

Manifesto Contract-first API Spec-driven development

Open system docs