Skip to content

feat(cli)!: take only a v2 API key or a Trunk JWT (TRUNK-23149, TRUNK-23372) - #1314

Merged
trunk-io[bot] merged 6 commits into
mainfrom
tylerbeebe/trunk-23149-23372-v2-key-or-jwt
Nov 17, 2026
Merged

trunk-io[bot] merged 6 commits into
mainfrom
tylerbeebe/trunk-23149-23372-v2-key-or-jwt

Conversation

@acatxnamedvirtue

@acatxnamedvirtue acatxnamedvirtue commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Part of TRUNK-23149 and TRUNK-23372

Based on main. #1313 (TRUNK-23148) and #1328 (TRUNK-23773) have merged; #1328 moved upload telemetry to the v2 CLI telemetry route. #1329 is stacked on this PR. Here the telemetry client follows the token kind: a v2 key on Authorization, a JWT on x-trunk-token. So telemetry works with either credential this PR accepts.

What changes

Token classification, in the new api/src/credential.rs, runs before any call:

  • A token starting trunk_v2_ is a v2 API key, sent as Authorization: Bearer. The gateway exchanges it.
  • Three non-empty base64url segments is a Trunk JWT, for example from trunk login --api-key. It goes only on x-trunk-token, since a JWT sent as a Bearer would hit the key lookup and fail.
  • Anything else is treated as the legacy org token and refused before any call. The message says 1.0.0 needs a v2 API key (Settings → Developer → API Keys) holding Upload test results, or to pin 0.17.x. test refuses before running the tests.

Errors:

  • 403 INSUFFICIENT_PERMISSIONS on uploads, quarantine-status or all-quarantined-tests: names the missing upload_test_results group and says to edit the key on the API Keys screen.
  • 401 with a JWT: says it's expired or invalid, with its exp time once that has passed, and to re-run trunk login --api-key or pass a v2 API key.
  • 403 on the fork lane's GitHub Actions login: says the collection must allow forked-PR uploads.
  • The error report shows these explanations instead of the generic org-slug hint.

Plugins:

  • test_report makes no call with a legacy token.
  • The rspec gem asks the new native RSpec::Trunk.token_refusal, then stays off with a warning.

Docs: a new README "Credentials" section, plus the --token help, CONTRIBUTING, and the gem's README and env docs.

JWT lifetime

auth-hydra's access tokens last at most 15 minutes, and there's no refresh. A JWT normally comes from trunk flakytests upload (trunk2 TRUNK-23916). It exchanges a stored org API key just before the launch, and the result can have as little as about a minute left. So a JWT suits only the upload itself. A long trunk-analytics-cli test run, or a gem run that looks up quarantine early and uploads late, should use a v2 API key; trunk flakytests test passes the key itself. The --token help, the 401 message and the docs say this.

Testing

Before merging

  • CI secrets: every step that runs the built CLI or the rspec gem now uses the new repo secrets TRUNK_STAGING_API_V2_TOKEN and TRUNK_PROD_API_V2_TOKEN (89f03aa). Those must be v2 API keys holding Upload test results. The Dynamic CI filter steps keep TRUNK_PROD_ORG_API_TOKEN, since they don't run analytics-cli.
  • The fake gem CI token is now trunk_v2_fake-token. That needed a trunk-ignore(checkov/CKV_SECRET_6) because it's a test value, not a secret.

🤖 Generated with Claude Code

@codecov-commenter

codecov-commenter commented Nov 12, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.39583% with 5 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (tylerbeebe/trunk-23148-v2-apis-only@28d508f). Learn more about missing BASE report.

Files with missing lines Patch % Lines
api/src/client/v2.rs 92.50% 3 Missing ⚠️
cli/src/summary_output/github.rs 87.50% 1 Missing ⚠️
cli/src/upload_command.rs 91.66% 1 Missing ⚠️
Additional details and impacted files
@@                          Coverage Diff                           @@
##             tylerbeebe/trunk-23148-v2-apis-only    #1314   +/-   ##
======================================================================
  Coverage                                       ?   86.05%           
======================================================================
  Files                                          ?       85           
  Lines                                          ?    19538           
  Branches                                       ?        0           
======================================================================
  Hits                                           ?    16814           
  Misses                                         ?     2724           
  Partials                                       ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment thread api/src/client/v2.rs Outdated
use crate::urls::TestCaseGuidScope;

const INSUFFICIENT_PERMISSIONS: &str = "INSUFFICIENT_PERMISSIONS";
const MISSING_UPLOAD_PERMISSION: &str = "lacks the Upload test results (`upload_test_results`) permission group. Grant it by editing the key in the Trunk web app under Settings → Developer → API Keys.";

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we support editing api keys currently? I don't think we do, they'd have to make a new one

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We do, actually! you cannot edit the name, description, or see the key again, but you can add or remove permissions

Comment thread api/src/client/mod.rs

/// Where the run's credential came from.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum RunCredential {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this an unnecessary redefinition of TokenKind?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not a redefinition. They're kept apart because they answer different questions:

  • TokenKind classifies the raw --token string, including Legacy. The CLI's and test_report's up-front refusals use it too, before any client exists.
  • RunCredential records what the client ended up holding, without the secret, so the 403/401 messages can name it. It has two cases TokenKind can't:
    • the JWT's exp, for the expired-JWT message;
    • the fork PR's GitHub Actions login, which is never a --token value.
  • V2Credential is the third: it carries the secret just long enough to build the client's headers.

Folding RunCredential into TokenKind would add a GithubActionsLogin case that can't come from a token string, and an exp that the classifiers would ignore.

Comment thread api/src/credential.rs Outdated

pub const LEGACY_TOKEN_MESSAGE: &str = concat!(
"This Trunk token is not a v2 API key. analytics-cli 1.0.0 needs a v2 API key: create one in ",
"the Trunk web app under Settings → Developer → API Keys, give it the Upload test results ",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can actually just give people a link for this. Omit the org slug and we'll redirect. Something like https://app.trunk.io/settings/developer-api-keys

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in c60c650. The refusal, the 401 and 403 messages, UNAUTHORIZED_CONTEXT, the --token help and the README now link to https://app.trunk.io/settings/developer/api-tokens. The page is settings/developer/api-tokens, not developer-api-keys. The web app sends an org-less /settings/… URL to the viewer's org (ORG_SCOPED_PATH_PREFIXES in the frontend).

Comment thread api/src/credential.rs Outdated
"This Trunk token is not a v2 API key. analytics-cli 1.0.0 needs a v2 API key: create one in ",
"the Trunk web app under Settings → Developer → API Keys, give it the Upload test results ",
"permission, and pass it with --token or TRUNK_API_TOKEN. To keep using your organization ",
"token, pin analytics-cli 0.17.x.",

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we should set an end date on this, or just append " until December 1, 2027"

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in c60c650: "To keep using your organization token until December 1, 2027, pin analytics-cli 0.17.x." The CLI, api and rspec gem tests check the date.

Comment thread cli/src/upload_command.rs Outdated
required_unless_present = "allow_forked_pr_uploads",
env = constants::TRUNK_API_TOKEN_ENV,
help = "Organization token. Defaults to TRUNK_API_TOKEN env var."
help = "A Trunk v2 API key (trunk_v2_...) with the Upload test results permission, from Settings → Developer → API Keys in the Trunk web app; or a Trunk JWT, which `trunk flakytests upload` sets for you from a key stored with `trunk auth api-key set` and which can have about a minute left, so it suits only the upload itself. The organization token is refused: pin analytics-cli 0.17.x to keep using it. Defaults to TRUNK_API_TOKEN env var."

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

likewise

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in c60c650 as well. The --token help now says "pin analytics-cli 0.17.x to keep using it until December 1, 2027", and links the page.

@acatxnamedvirtue
acatxnamedvirtue force-pushed the tylerbeebe/trunk-23149-23372-v2-key-or-jwt branch from 6ea6c13 to 129c31b Compare November 16, 2026 22:26
@acatxnamedvirtue
acatxnamedvirtue force-pushed the tylerbeebe/trunk-23148-v2-apis-only branch from eb766c5 to 28d508f Compare November 16, 2026 22:52
@acatxnamedvirtue
acatxnamedvirtue force-pushed the tylerbeebe/trunk-23149-23372-v2-key-or-jwt branch from 129c31b to 49c473e Compare November 16, 2026 22:55
acatxnamedvirtue and others added 4 commits November 17, 2026 13:14
…-23372)

analytics-cli 1.0.0 reads what `--token` / `TRUNK_API_TOKEN` holds before
it calls Trunk:

- `trunk_v2_...` is a v2 API key, sent as `Authorization: Bearer` for the
  gateway to exchange.
- Three non-empty base64url segments is a Trunk JWT, sent on
  `x-trunk-token` (#1293's header) and never as a bearer.
- Anything else is the organization token, refused before any call with
  how to create a v2 key (Settings → Developer → API Keys), the Upload
  test results permission it needs, and the 0.17.x pin. `upload` and
  `test` exit with an error, and `test` refuses before running the tests.
  The fork lane's `GITHUB_TOKEN` exchange is unchanged.

On the three CLI endpoints, a 403 `INSUFFICIENT_PERMISSIONS` names the
missing `upload_test_results` permission group and how to grant it, and
a 401 for a JWT says it is expired or invalid (with its `exp` when past)
and to re-run `trunk login --api-key` or pass an API key. The error
report shows that explanation in place of the generic org-slug hint.

A Trunk JWT lasts 15 minutes (auth-hydra's `ttl.access_token`), which a
long `test` run or a plugin that looks up quarantine early and uploads
late can outlive. The CLI does not refresh it; the 401 message and the
docs say to mint it right before the upload step.

`test_report` and the rspec gem apply the same rule: the gem asks the
native extension (`RSpec::Trunk.token_refusal`) and stays off with a
warning for an organization token.

Telemetry is unchanged and still sends the token on `x-api-token`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…UNK-23916)

`trunk login --api-key` was canceled. A Trunk JWT now reaches analytics-cli
from `trunk flakytests upload`, exchanged from a key stored with
`trunk auth api-key set`, and can have about a minute left, so the help
text, the expired-JWT message and the docs point there instead of telling
users to mint a 15-minute JWT themselves.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… comment

TRUNK-23371 is canceled; the JWT now comes from `trunk flakytests upload`,
and a gem run should use a v2 API key (see the README's Credentials).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…149)

analytics-cli 1.x refuses the organization token, so every step that runs
the built CLI or the rspec gem now uses TRUNK_PROD_API_V2_TOKEN and
TRUNK_STAGING_API_V2_TOKEN. The Dynamic CI filter steps keep
TRUNK_PROD_ORG_API_TOKEN: they don't run analytics-cli.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@acatxnamedvirtue
acatxnamedvirtue force-pushed the tylerbeebe/trunk-23149-23372-v2-key-or-jwt branch from 89f03aa to 639c348 Compare November 17, 2026 13:18
@acatxnamedvirtue
acatxnamedvirtue changed the base branch from tylerbeebe/trunk-23148-v2-apis-only to main November 17, 2026 13:18
@trunk-io

trunk-io Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

😎 Merged successfully - details.

acatxnamedvirtue and others added 2 commits November 17, 2026 13:25
…-token pin (TRUNK-23149)

Review follow-up. Messages, the --token help and the README link to
https://app.trunk.io/settings/developer/api-tokens, which the web app sends to
the viewer's org. The organization token keeps working on 0.17.x until
December 1, 2027.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… tests

ubuntu-latest is now ubuntu-26.04, where qemu-user-static is a virtual
package with no installation candidate, so apt-get exits 100 before the
smoke test runs. qemu-user-binfmt provides the user-mode emulators and
registers binfmt_misc on both 24.04 and 26.04.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@trunk-io
trunk-io Bot merged commit e5df5d4 into main Nov 17, 2026
23 checks passed
trunk-io Bot pushed a commit that referenced this pull request Nov 17, 2026
#1335)

#1314 moved the release smoke test to the v2 API keys, but it runs the
latest published CLI and gem (0.17.0), which send --token as an
organization token. trunk1 finds no org for a v2 key, so
createBundleUpload and the quarantine lookup 404 on staging and
production.

determine_releases now records whether each release is 1.0.0 or later.
Releases before 1.0.0 get the organization token, and later ones get the
v2 key, so the run switches over when 1.0.0 is published. The gem jobs
now list determine_releases in needs so they can read that output.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

3 participants