# Auth

Activate when code touches token management, credential resolution, git auth flows...

- Repository: https://github.com/microsoft/apm (4171 stars)
- Category: Git and review
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add microsoft/apm --skill auth -g -a claude-code -y`
Codex: `npx skills add microsoft/apm --skill auth -g -a codex -y`
Cursor: `npx skills add microsoft/apm --skill auth -g -a cursor -y`
Gemini CLI: `npx skills add microsoft/apm --skill auth -g -a gemini-cli -y`

## Description

Activate when code touches token management, credential resolution, git auth flows, GITHUB_APM_PAT, ADO_APM_PAT, AuthResolver, HostInfo, AuthContext, or any remote host authentication -- even if 'auth' isn't mentioned explicitly.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Auth Skill

[Auth expert persona](../../../.apm/agents/auth-expert.agent.md)

## When to activate

- Any change to `src/apm_cli/core/auth.py` or `src/apm_cli/core/token_manager.py`
- Code that reads `GITHUB_APM_PAT`, `GITHUB_TOKEN`, `GH_TOKEN`, `ADO_APM_PAT`
- Code using `git ls-remote`, `git clone`, or GitHub/ADO API calls
- Error messages mentioning tokens, authentication, or credentials
- Changes to `github_downloader.py` auth paths
- Per-host or per-org token resolution logic

## Key rule

All auth flows MUST go through `AuthResolver`. No direct `os.getenv()` for token variables in application code.

## Canonical reference

The full per-org -> global -> credential-fill -> fallback resolution flow is in [`docs/src/content/docs/getting-started/authentication.md`](../../../docs/src/content/docs/getting-started/authentication.md) (mermaid flowchart). Treat it as the single source of truth; if behavior diverges, fix the diagram in the same PR.

## Bearer-token authentication for ADO

Azure DevOps Services (`dev.azure.com`, `*.visualstudio.com`) use this chain:

1. `ADO_APM_PAT` env var if set
2. AAD bearer via `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798` if `az` is installed and `az account show` succeeds
3. Operation-time path-scoped `git credential fill` after HTTP 401/403 or a recognized Git authentication failure (`is_ado_auth_failure_signal`)
4. Otherwise: `AdoAuthChainExhaustedError` from `try_with_fallback`, or `build_error_context` on resolve-time failures

Azure DevOps Server hosts (`ADO_HOST` / `APM_ADO_HOSTS`) skip az bearer: PAT, then fill.

`ADO_APM_PAT` is the env var name used by the auth flow. The AAD bearer source constant lives in `src/apm_cli/core/token_manager.py` as `GitHubTokenManager.ADO_BEARER_SOURCE = "AAD_BEARER_AZ_CLI"`.

**Stale-PAT fallback:** on HTTP 401/403 or a recognized Git authentication failure, APM tries an available az bearer. A successful bearer retry emits:

The rest: https://github.com/microsoft/apm/blob/HEAD/.agents/skills/auth/SKILL.md