Skip to content

Trusted publishing: GitHub Actions OIDC exchange and composite action - #14

Merged
roncodes merged 1 commit into
v2from
feat/trusted-publishing
Nov 19, 2026
Merged

roncodes merged 1 commit into
v2from
feat/trusted-publishing

Conversation

@roncodes

Copy link
Copy Markdown
Member

Summary

flb publish can now publish from GitHub Actions without any stored secret. A job with id-token: write requests a GitHub OIDC token and trades it for a short-lived, publish-only flbt_ token for the extension. This repo also gains a composite action, fleetbase/fleetbase-cli/action@v2, that wraps it.

CLI

  • Token order for flb publish: FLB_TOKEN, then the OIDC exchange when ACTIONS_ID_TOKEN_REQUEST_URL/_TOKEN are set (or --oidc), then the stored login. --no-oidc skips the exchange. No other command changes.
  • Exchange: the CLI GETs ${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=<registry host name> with the request token as bearer (FLB_OIDC_AUDIENCE overrides the audience). It then calls POST v1/auth/oidc/github with {token, extension}, where extension is the npm package name, else the composer name.
  • Timing: the exchange runs after the build, so the token's lifetime goes to the upload and checks. It runs again when the token is within 2 minutes of expires_at, because a 15 m check wait can outlast a ~15 min token. To support this, RegistryClient gets a tokenProvider option.
  • Errors:
    • Missing or half-set OIDC variables, or GitHub refusing the token request, point at permissions: id-token: write.
    • A 401 from the exchange names the audience that was requested.
    • A 403 names the repository, workflow file and ref to set up in Studio → Access.
    • A 404 or 422 gets a clear message.
    • A GitHub Actions job with no token at all gets the id-token hint added to "Not logged in".
  • Listings: in OIDC mode, publish never creates a listing (POST v1/publisher/extensions) and never adds a package to one. It fails and says what to do instead.
  • Token handling: flbt_ tokens count as service tokens, not legacy. They are redacted in output, and so are JWTs. Neither token is printed or written to disk.
  • Small fix: the "Added … package to the listing" message used to print true instead of the package kind.

Action (action/)

  • Inputs: path, registry, channel, submit (default true), wait (default true), timeout, notes, notes-file, token, oidc-audience, install-command, args, cli-version (default ^2.0.0-0, or source to build the CLI from the action's own checkout), node-version (default 22).
  • Outputs: release-id, version, status, channel, extension.
  • Job summary: the step writes one with the check results.
  • Exit status: the step fails when flb publish fails. The outputs are still set whenever the upload happened.
  • Example: action/examples/publish-on-tag.yml publishes on tag push. README.md has a new "Publishing from GitHub Actions" section, and action/README.md covers the action.

Notes

  • @fleetbase/cli on npm is still at 0.0.6. The default cli-version: ^2.0.0-0 only resolves once a v2 build that includes this change is published. Until then, use cli-version: source.
  • The build needs no extension dependencies: npm pack plus the composer autoload files. The exception is prepare/prepack scripts; for those, use install-command or args: --ignore-scripts.
  • The server side, POST /v1/auth/oidc/github plus trusted publishers in Studio → Access, is being built in fleetbase/registry.

Tests

  • npm run typecheck: clean.
  • npm test: 114/114 pass, including the 9 new tests in test/unit/oidc.test.ts.
  • Installer tests: 3/3 pass.
  • The action's publish script was dry-run locally against a stub CLI (argument building, token passthrough, outputs, summary, exit code). It has not been run on a real runner yet.

`flb publish` can publish without a stored secret: in a job with
`id-token: write` it requests the GitHub OIDC token (audience: the
registry's host name, FLB_OIDC_AUDIENCE overrides), exchanges it with
POST /v1/auth/oidc/github for a short-lived flbt_ token scoped to the
extension (named by its npm package, else composer), and uses that token
for the listing lookup, upload and checks.

- Token order for publish: FLB_TOKEN, then the exchange when
  ACTIONS_ID_TOKEN_REQUEST_URL/TOKEN are set (or --oidc), then the stored
  login; --no-oidc skips it. Other commands are unchanged.
- The exchange runs after the build and again when the token is within two
  minutes of expiry (RegistryClient gains a tokenProvider), so long check
  runs outlive the ~15 minute token.
- Actionable errors: missing OIDC variables or a refused GitHub request
  point at `permissions: id-token: write`; 401 names the audience; 403
  names the repository, workflow file and ref to configure in Studio →
  Access. A GitHub Actions job with no token at all gets the same hint.
- Trusted publishing never creates a listing or adds a package to one.
- flbt_ tokens are service tokens (not legacy) and are redacted in output,
  as are JWTs. Neither token is printed or written to disk.

action/: a composite action (fleetbase/fleetbase-cli/action@v2) that sets
up Node, installs @fleetbase/cli (or builds it from the action's checkout
with cli-version: source), runs `flb publish --json` and exposes
release-id, version, status, channel and extension, with a job summary.
action/examples/publish-on-tag.yml publishes on tag push. README documents
the setup.
@roncodes
roncodes merged commit 886e53b into v2 Nov 19, 2026
5 checks passed
@roncodes
roncodes deleted the feat/trusted-publishing branch November 19, 2026 05:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant