Connect in 3 steps

Work in a clone of the repository that holds your OpenAPI document.

1. Run vendor init

   It finds your OpenAPI document and your SDK packages, and shows the two files it would write.

   Create the filessh

   npx @upseam/cli vendor init

   You should see both files and a y/N question before anything is written.

2. Merge the two files

   vendor init writes upseam.vendor.yml and .github/workflows/upseam-vendor.yml. Keep the workflow at that path.

3. Cut a tagged release

   Self-serve publishing runs from tags only.

   Publish a releasesh

   gh release create v2.0.0 --generate-notes

   You should see the registration in the Actions log after each release.

The first release registers your repository with Upseam. There is no form and no manual registration.

#Check how it went

npx @upseam/cli vendor status

vendor status [path] reads the repository from the git remote origin and asks Upseam, with no token, what it knows. It prints whether the repository is registered, its state, the holds, each package with its proof or what is missing, and the last release. It exits 0 when the call works, also for a repository that is not registered, and 1 on a network error or a rejected name. --json prints the answer as it is and --upseam-url <url> points to another Upseam App.

Preview the events of a release before you publish it:

npx @upseam/cli vendor publish --dry-run
npx @upseam/cli vendor publish --dry-run --base v1.0.0 --json

#What vendor init does

• It finds openapi.yaml, openapi.yml or openapi.json at the root, or any openapi* or swagger* file up to four directories deep. It also finds the package names of your SDKs in package.json and pyproject.toml, and skips a package.json with "private": true.
• It shows both files and asks y/N before writing. Without a terminal it needs --yes or --dry-run.
• --yes writes without asking, --dry-run writes nothing, --force replaces an existing file, --spec <path> picks the document and --changelog <url> sets the changelog link.
• It then offers the README badge, prints the link to your page in the App and prints the docs snippet. See Badge and docs snippet.

#The workflow

The workflow runs on every published release, and by hand with workflow_dispatch on a tag. It diffs the document between the previous release tag and the release, then sends the events. A release with no earlier tag, or with no API changes, sends no events. It still reaches Upseam, so the first one registers you and every one refreshes the state.

name: upseam-vendor
on:
  release:
    types: [published]
  workflow_dispatch:
permissions:
  contents: read
  id-token: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: upseam/action@v0
        with:
          mode: vendor

#The config

upseam.vendor.yml sits at the repository root.

provider: acme-mail
name: Acme Mail
spec: openapi.yaml
versioning: path
changelog: https://docs.acme.example/changelog
packages:
  npm: [acme-mail]
  pypi: [acme-mail]

#Connect from the App

The App lists the repositories where you have admin rights under For API vendors. Pick one to see the OpenAPI document and the packages Upseam detected, a preview of the events your next release would send and the registration status. You can correct the provider id and the packages.

Setup writes the same files as vendor init. When the installation grants the Workflows permission, Upseam makes one commit on a branch upseam/vendor-setup and opens a pull request. Without it, the page shows the files with Copy buttons and the vendor init command, and writes nothing. Upseam does not request the permission.

#How the Action stays safe

• No secret. The job asks GitHub for a short-lived token that names your repository, its owner and the tag of the run. The token is valid only at the Upseam deployment it is sent to, the Action never prints it, and Upseam accepts each token once.
• Ownership. Upseam checks the token signature against the GitHub Actions keys. A fork or any other repository has its own registration and proves its own packages.
• Data, not code. The request carries the manifest, the release tag and link, and the change events. No source code is sent, only names from your OpenAPI document. Upseam validates the events and never runs anything from them.
• Local references only. A $ref to other files or URLs is refused, so the diff reads nothing outside the document.