Repository navigation
Description
Is your feature request related to a problem? Please describe.
There is no way to ask APM "do you have a credential for this host, and is it any good?" before something fails. The closest surface is apm doctor, whose auth check is a single hardcoded probe (commands/marketplace/doctor.py:200-215):
token = resolver.resolve("github.com").token
has_token = bool(token)
auth_detail = "Token detected" if has_token else "No token; unauthenticated rate limits apply"That is github.com only, reports presence rather than validity, and offers no remediation. For GitLab, GHES, or any self-managed host, it says nothing at all.
The cost shows up as a recurring shape in this tracker: an auth problem surfacing as something other than an auth problem, each fixed individually downstream.
- [BUG] Localised git stderr breaks auth-failure classification, suppressing the token retry #2533 — localised git stderr breaks auth-failure classification, suppressing the token retry
- [BUG] Clone failures on github.com are reported as "network error, not an auth failure" — git stderr is dropped when wrapping CalledProcessError #2529 — clone failures reported as "network error, not an auth failure" (self-closed for a wrong root cause; the reporter noted the user-visible problem is real)
- [BUG] Single-file deps from private repos fail without PAT even when git credential helpers are configured #331 — single-file deps from private repos fail without a PAT even when git credential helpers are configured
- apm marketplace add fails to authenticate when fetching marketplace.json from private repositories #669 —
apm marketplace addfails to authenticate fetchingmarketplace.jsonfrom private repos - Installer and self-update ignore token env vars for GitHub release lookup #1582 — installer and self-update ignore token env vars for GitHub release lookup
Each was a real bug and each fix was correct. But they share a precondition: the user had no way to find out their credential situation before the operation that depended on it. The diagnosis always arrives inside a failure of something else.
A second, quieter cost is that the resolution order is not discoverable. TOKEN_PRECEDENCE["modules"] is GITHUB_APM_PAT, GITHUB_TOKEN, GH_TOKEN then gh auth token, then the credential helper — env vars winning over helpers. A user who already exports GH_TOKEN has no way to learn APM will use it, so they mint a PAT they did not need.
Describe the solution you'd like
A small read-mostly command, apm auth HOST, that answers three questions and does nothing else:
$ apm auth github.com
[+] github.com: using credential from GH_TOKEN.
[i] Add --check to validate it against the API.
$ apm auth gitlab.com --check
[!] gitlab.com: the credential from GITLAB_TOKEN was rejected (HTTP 401).
An OAuth session token (e.g. from 'glab auth login') works for git but
not for the REST API -- you need a personal access token.- Which credential does APM resolve for this host, and from where — naming the source, so precedence is observable rather than documented.
- Does it actually work (
--check) — validating against the REST API, because a tokengit cloneaccepts is not automatically one the API accepts. The GitLab OAuth-session-token case above is the motivating example. - If there is none, how do I get one — opening the host's token page with name and scopes prefilled, then accepting a paste.
Deliberate non-goals, to keep the surface small:
- It does not register marketplaces or install anything.
apm marketplace addandapm installalready do that and report their own errors better than a second pre-flight here could. - It does not write to
~/.apm/config.json.AuthResolverreads only env vars and credential helpers, so storing a token there would be inert. It prints theexportline instead;eval "$(apm auth <host> --export)"makes that a one-liner. - It does not mutate any credential store. Where a shadowing keychain entry is detected it is reported, never erased.
- It does not change
classify_host. Hosts that resolve asgenericstill exit non-zero — which fix: preserve credential helpers for generic marketplace git #2594's transport policy suggests is the intended behavior for them, not a gap — with an error namingGITHUB_HOST/GITLAB_HOSTas the fix.
--check distinguishes rejected from could not find out, and only the first advises minting a new token. An unreachable API, a 5xx, or a GitHub App installation token that cannot be validated all keep the credential and exit 0. This matters in CI: Actions' own GITHUB_TOKEN is a ghs_ installation token with no user context, so GET /user answers 403 even though it reads repository contents fine — a pre-flight check must not fail that build.
Describe alternatives you've considered
- Extend
apm doctorinstead. Reasonable, and I would defer to maintainers here. The reason I lean toward a separate verb:doctoris a whole-environment pass/fail sweep, whereas this is a per-host question with an interactive remediation path and a machine-readable--exportmode. Folding a prompt-and-paste flow into a diagnostics sweep muddies both. The two are complementary, and thegeneric-host error already defers toapm doctor. - Better error messages at each failure site. This is what the issues above already did, and each fix was right. It does not give the user a way to ask before the failure, and the surface area keeps growing.
- Documentation only. The resolution order is documented, but a table cannot tell you which var is set on your machine or whether that token still works.
Additional context
I have this working against current main and am happy to open a PR if the idea is wanted. It is additive — a new command, CLI wiring, docs and tests — with no changes to AuthResolver, classify_host, or token_manager, so it should not interact with the auth work already in flight.
Opening as an issue first per CONTRIBUTING rather than sending an unsolicited feature PR. Equally happy to fold it into apm doctor instead, or drop it, if either fits the roadmap better.
One small thing that stands alone regardless of what happens to this proposal: GH_TOKEN is in TOKEN_PRECEDENCE["modules"] but missing from the documented resolution order, so a user who has only GH_TOKEN set reads the docs as saying it is unused and mints a PAT they do not need.
Metadata
Metadata
Assignees
Labels
Type
Projects
- StatusShow more project fieldsDone
Activity
jonioliveira commentedon Sep 3, 2026
Opened #2789 as a draft with the implementation, so there is running code to look at rather than a description of it.
To be clear about what that does and does not mean: the questions above are still open. If
apm doctoris the better home for this, or if it is not a gap you want closed, closing the draft costs nothing — I would rather you judge the idea than feel presented with a fait accompli.github-actions commentedon Sep 9, 2026
Triage decision
needs-design
Proposed labels
Milestone
null -- open-milestone read failed (401 from milestones API); no milestone assigned this run.
Suggested next action
Settle whether this ships as a new
apm auth HOSTcommand or folds intoapm doctor, and specify the --check/--export contract (validation semantics, non-goals, CI installation-token handling) before implementation.Suggested issue comment
Per-lens notes (collapsed)
DevX UX Expert -- User-Need Reviewer
Directly answers a real pre-flight question users have no way to ask today ("do you have a credential for this host, and is it good"). Aligns with the package-manager mental model of discoverable, inspectable state rather than surprise failures.
Supply Chain Security Expert -- Risk-Surface Reviewer
Squarely theme/security: touches credential resolution, token precedence disclosure, and validation against host APIs. The care taken around CI installation tokens (GITHUB_TOKEN as ghs_ token) and never mutating credential stores is a strong sign the author understands the risk surface; still needs an explicit design review before landing given the auth-boundary sensitivity.
OSS Growth Hacker -- Contributor-Tone Reviewer
jonioliveira has only 2 prior interactions on this repo -- activating tone tuning. Suggested reply above stays warm and points to a concrete next step (a short design thread) rather than a flat accept/reject, appropriate for a detailed first-time-ish proposal.
Python Architect -- Architecture Reviewer
New command surface plus a precedence-disclosure and validation contract spanning AuthResolver-adjacent code is a cross-cutting design decision (interface + non-goals need ratification) even though the author states no changes to AuthResolver/classify_host/token_manager internals are required. Recommending status/needs-design.
Doc Writer -- Documentation Reviewer
A new command needs new reference docs (command page, resolution-order table correction for GH_TOKEN) regardless of which of the two implementation paths (new verb vs. doctor extension) is chosen.
APM CEO -- Triage Arbiter
Good idea, real problem, but the doctor-vs-new-verb question and the --check/--export contract are exactly the kind of interface decision that should be settled once rather than negotiated inside a PR review. needs-design, theme/security, area/cli, type/feature.
{ "decision": "needs-design", "decision_detail": "Settle apm auth vs apm doctor extension, and the --check/--export contract, before implementation.", "theme": "theme/security", "areas": ["area/cli"], "type": "type/feature", "status": "status/needs-design", "priority": null, "preserved_labels": [], "milestone": null, "next_action": "Settle whether this ships as a new `apm auth HOST` command or folds into `apm doctor`, and specify the --check/--export contract (validation semantics, non-goals, CI installation-token handling) before implementation.", "comment_markdown": "This is a strong, well-reasoned proposal -- the recurring pattern of auth failures surfacing as other kinds of errors is real and well-documented across the linked issues. Before a PR lands we need a short design decision: separate `apm auth` verb vs. folding into `apm doctor`, and the exact semantics of `--check` (rejected vs. could-not-verify) and `--export`. Flagging as needs-design rather than a blocker -- the shape you propose looks sound and additive. No milestone assigned yet (milestone read failed this run)." }github-actions commentedon Sep 10, 2026
Triage decision
needs-design
Proposed labels
Milestone
null
Suggested next action
Design a per-host, per-credential validation surface (e.g.
apm auth checkor an expandedapm doctorauth section) that reports validity per host and offers concrete repair steps for GitHub.com, GHES, and GitLab.Suggested issue comment
Per-lens notes (collapsed)
DevX UX Expert -- User-Need Reviewer
Real, recurring user need: proactive credential diagnosis before a failure, not another downstream symptom fix. Maps to a concrete gap in
apm doctor's single hardcoded github.com probe. The ask is well-grounded in prior issue history rather than speculative.Supply Chain Security Expert -- Risk-Surface Reviewer
Directly touches auth/credential resolution across multiple hosts -- theme/security is required. Any repair flow must be careful not to leak token values in diagnostic output or write credentials insecurely.
OSS Growth Hacker -- Contributor-Tone Reviewer
Not activated -- author association is NONE but the issue demonstrates deep prior-issue research and repo familiarity; a standard courteous, substantive tone suffices without special first-timer framing.
Python Architect -- Architecture Reviewer
This is a genuine cross-cutting design question: a new auth-validation abstraction that must plug into AuthResolver, doctor, and potentially a new CLI subcommand across multiple host types. Feasible, but the interface (what "validate" returns, how repair actions are modeled per host) needs to be settled before code lands. Confirms status/needs-design.
Doc Writer -- Documentation Reviewer
Not activated -- no concrete doc surface exists yet since the feature interface is undecided; docs work will follow once the design lands.
APM CEO -- Triage Arbiter
Strong problem statement backed by five prior issues. The scope (multi-host credential validation + repair) is cross-cutting enough to require a design pass before code. Setting status/needs-design, theme/security, area/cli, no milestone.
{ "decision": "needs-design", "decision_detail": "", "theme": "theme/security", "areas": ["area/cli"], "type": "type/feature", "status": "status/needs-design", "priority": null, "preserved_labels": [], "milestone": null, "next_action": "Design a per-host, per-credential validation surface (e.g. apm auth check or an expanded apm doctor auth section) that reports validity per host and offers concrete repair steps for GitHub.com, GHES, and GitLab.", "comment_markdown": "Thanks for tracing the recurring pattern across #2533, #2529, #331, #669, and #1582 -- that's a strong case that credential visibility is a real, repeated user cost, not five unrelated bugs. This needs a design pass before implementation: what \"validate\" means per host type, how repair suggestions differ per host, and how this surface composes with `apm doctor`. Flagging as needs-design; a short design note covering the per-host validation contract and its relationship to AuthResolver would unblock this." }feat(cli): add `apm auth` for git host credentials (#2788) (#3134)