Skip to content

[FEATURE] apm auth: report and repair a host's credential before something fails #2788

Closed

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.

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.
  1. Which credential does APM resolve for this host, and from where — naming the source, so precedence is observable rather than documented.
  2. Does it actually work (--check) — validating against the REST API, because a token git clone accepts is not automatically one the API accepts. The GitLab OAuth-session-token case above is the motivating example.
  3. 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 add and apm install already do that and report their own errors better than a second pre-flight here could.
  • It does not write to ~/.apm/config.json. AuthResolver reads only env vars and credential helpers, so storing a token there would be inert. It prints the export line 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 as generic still 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 naming GITHUB_HOST / GITLAB_HOST as 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 doctor instead. Reasonable, and I would defer to maintainers here. The reason I lean toward a separate verb: doctor is a whole-environment pass/fail sweep, whereas this is a per-host question with an interactive remediation path and a machine-readable --export mode. Folding a prompt-and-paste flow into a diagnostics sweep muddies both. The two are complementary, and the generic-host error already defers to apm 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.

Activity

  1. jonioliveira commented on Sep 3, 2026

    @jonioliveira
    ContributorAuthor

    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 doctor is 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.

  2. added
    area/cliCLI command surface, flags, help text (cross-cutting).
    type/featureNew capability, new flag, new primitive.
    status/needs-designDesign discussion required before implementation; not scope approval by itself.
    on Sep 9, 2026
  3. github-actions commented on Sep 9, 2026

    @github-actions

    Triage decision

    needs-design

    Proposed labels

    theme/security
    area/cli
    type/feature
    status/needs-design
    

    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 HOST command or folds into apm doctor, and specify the --check/--export contract (validation semantics, non-goals, CI installation-token handling) before implementation.

    Suggested issue comment

    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).

    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)."
    }

    Triage status: agentic proposal pending human ratification.
    Silence is approval. Maintainers can:

    • Override any label or milestone above by editing it directly --
      human edits are authoritative and will not be reverted on
      subsequent runs.
    • Re-trigger triage by applying the status/needs-triage label, or
      by removing status/triaged to enroll the issue in the next
      daily sweep.

    Posted by the Triage Panel workflow. See packages/apm-triage-panel for the panel skill.

    Generated by Triage Panel · copilot · auto · 165.9 AIC · ⌖ 21.2 AIC · ⊞ 14.1K · ◷

  4. github-actions commented on Sep 10, 2026

    @github-actions

    Triage decision

    needs-design

    Proposed labels

    theme/security
    area/cli
    type/feature
    status/needs-design
    

    Milestone

    null

    Suggested 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.

    Suggested issue comment

    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.

    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."
    }

    Triage status: agentic proposal pending human ratification.
    Silence is approval. Maintainers can:

    • Override any label or milestone above by editing it directly -- human edits are authoritative and will not be reverted on subsequent runs.
    • Re-trigger triage by applying the status/needs-triage label, or by removing status/triaged to enroll the issue in the next daily sweep.

    Posted by the Triage Panel workflow. See packages/apm-triage-panel for the panel skill.

    Generated by Triage Panel · copilot · auto · 76.9 AIC · ⌖ 22.5 AIC · ⊞ 14.1K · ◷

  5. added
    status/triagedAutomated advice completed; deduplication only. Not human approval; silence is not approval.
    on Sep 10, 2026
  6. added
    triage/recommendedAutomated advice completed; not human scope approval.
    and removed
    status/triagedAutomated advice completed; deduplication only. Not human approval; silence is not approval.
    on Sep 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/cliCLI command surface, flags, help text (cross-cutting).status/acceptedHuman scope approval; verify the issue's approval record and review contact before work.status/needs-designDesign discussion required before implementation; not scope approval by itself.triage/recommendedAutomated advice completed; not human scope approval.type/featureNew capability, new flag, new primitive.

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions