Onboarding a provider for `ss state`

When ss state refresh reports skipped for a provider, it’s because that provider’s API token isn’t in the vault. Each adapter’s preflight() error message includes the exact ss vault set-key command — this runbook gathers them in one place.

After running the right set-key and a fresh ss state refresh, the provider’s resources will start appearing in ss state list.

Railway

1. Generate a Personal Access Token at https://railway.app/account/tokens (no scope picker — Railway PATs have full account access)
2. Store it:

   ss vault set-key railway api_key=<token>

3. Verify: ss state refresh --provider=railway should report a non-zero discovery count.

Hetzner Cloud

1. Open https://console.hetzner.cloud → your project → Security → API tokens → Generate API token
2. Permissions: Read & Write (Read-only is enough for inventory, but the provisioner needs Write — single token is fine).
3. Store:

   ss vault set-key hetzner api_token=<token>

4. Verify: ss state refresh --provider=hetzner

Supabase

1. Generate a Personal Access Token at https://supabase.com/dashboard/account/tokens
2. Store:

   ss vault set-key supabase api_key=<sbp_...>

3. Verify: ss state refresh --provider=supabase

The same token powers ss vault rotate-supabase for refreshing the per-project SUPABASE_CONNECTION_STRING + service-role key entries.

Cloudflare

1. Generate an API token at https://dash.cloudflare.com/profile/api-tokens → Create Token → Custom token
2. Permissions needed:
   • Account → Account Settings:Read
   • Account → Cloudflare Pages:Read
   • Account → Workers Scripts:Read
   • Zone → Zone:Read
3. Account/Zone resources: all accounts, all zones.
4. Store:

   ss vault set-key cloudflare api_token=<token>

5. Verify: ss state refresh --provider=cloudflare

GitHub

1. Create a token at https://github.com/settings/tokens
   • Fine-grained (preferred) — give it Contents: read and Metadata: read on every repo you want indexed (or “All repos I have access to”).
   • Classic — repo scope is sufficient.
2. Store:

   ss vault set-key github api_key=<gho_... | ghp_...>

3. Verify: ss state refresh --provider=github

GitHub’s API has a rate ceiling at 5,000 reqs/hr. A full sweep does roughly 2 + 2 × repos requests (one for /user/repos and /user/orgs, then workflows + deployments per repo). At ~50 repos you’re well under the ceiling; at ~500+ consider running the sweep less often or filter by org via fine-grained scope.

Inspecting what’s stored

ss vault list-keys <provider>         # one provider
ss vault list-all                     # everything

ss state providers lists what’s registered in the inventory layer even if a vault key is missing — useful for seeing what’ll come online once a new key is added.

Rotating a token

ss vault delete-key <provider> <key>
ss vault set-key    <provider> <key>=<new-token>

No restart needed; the next ss state refresh reads the new value.