GH Accounts

A native VS Code extension for managing GitHub CLI accounts on GitHub.com and GitHub Enterprise. Hosts group accounts in the GH Accounts Activity Bar view. Account rows show username, active state, and authentication health; row actions switch or log out. The status bar opens an account Quick Pick whose labels include the host.

Switching changes gh’s active account for that host in its shared configuration. It does not create a workspace-specific identity or change Git commit author settings. Other terminals, tools, and workspaces using that same gh configuration see the change. Git credential helpers already configured to use gh may consequently use the newly selected account.

Install

Requires VS Code 1.95 or newer, a trusted workspace, and GitHub CLI installed on the machine running the extension.

Install GH Accounts from the Visual Studio Code Marketplace, or run:

code --install-extension am-asas.gh-accounts

Install a local VSIX

1. In VS Code, open Extensions, then … → Install from VSIX….
2. Select gh-accounts-0.1.0.vsix from this directory.
3. Reload if prompted, then open GH Accounts in the Activity Bar.

Alternatively, from this directory:

code --install-extension .\gh-accounts-0.1.0.vsix

Installing the extension does not install GitHub CLI. Local VSIX packages use the publisher identifier am-asas.

Use

• Refresh probes gh and rechecks all accounts. The view distinguishes loading, empty, missing CLI, incompatible CLI, errors, and last known data after a failed refresh.
• Add Account accepts a DNS hostname such as github.com, git.example.com, or a single-label Enterprise hostname. URLs, ports, paths, whitespace inside the name, and shell syntax are rejected. Complete gh auth login --web --hostname <host> --skip-ssh-key in the dedicated native task terminal. The direct process receives arguments separately; there is no shell command interpolation. Browser authorization and any remaining gh prompts belong to gh. Decline Git integration prompts if you do not want gh to configure Git credential helpers. SSH key generation/upload prompts are skipped.
• Login refreshes accounts after the process finishes, fails, or is cancelled. Refresh remains available during and after login; an intermediate refresh may still show pre-login accounts. Cancel with the progress notification or terminate the GH Accounts task terminal. Login times out after ten minutes.
• Switch Account runs gh auth switch --hostname <host> --user <username>, then refreshes. No account is marked active optimistically. A failure triggers another status check; if that check fails, previous accounts are clearly marked Last known.
• Log Out asks for confirmation naming username @ host, then runs gh auth logout --hostname <host> --user <username>. This removes local authentication without revoking the token. gh may select a remaining account on that host. The operation can be cancelled from its progress notification.
• Command Palette equivalents are under GH Accounts. The status bar and account rows open a keyboard-accessible Quick Pick; view row actions also appear in the context menu. Native TreeView, Quick Pick, theme icons, and theme colors follow VS Code themes.

Authentication health comes from each JSON entry’s state (success, error, or timeout) and any nonempty error indicator. A zero exit code with unhealthy entries is not treated as universally healthy. Error details, tokens, scopes, and credential paths are not shown or logged. Unknown environment identities remain visible if gh cannot determine their username. Health reports can reflect invalid authentication or host/network problems; they do not guarantee later operations will succeed.

Environment tokens

GH Accounts detects the presence of GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, and GITHUB_ENTERPRISE_TOKEN in the extension host’s environment, never their values. About Shared Accounts and Environment Tokens reports their names. Empty variables are detected but do not override authentication.

An applicable nonempty variable overrides saved credentials. The host view and Quick Pick explain this, and switch, logout, and login for that host are blocked. Environment identities have no saved-account row actions. The extension never unsets or modifies token variables or claims that changing a saved account changes the effective identity while an override applies. To manage saved accounts, change your environment yourself and restart VS Code or the remote extension host so it inherits the new environment. Variables exported in a separate terminal do not necessarily reach the extension host.

Task terminals can have terminal.integrated.env.* overrides. Login is blocked if relevant token or gh configuration/home settings there differ from the extension process, avoiding a login into a different credential configuration. Align those settings yourself; no values are printed or automatically removed. Noninteractive commands run from the extension host home directory and use its environment and gh configuration.

CLI detection, trust, and remote work

The extension resolves gh (gh.exe on Windows) from absolute PATH entries and checks gh --version plus the help for all required auth commands/flags. Capability checks, rather than an assumed version number, determine compatibility. Install or upgrade gh using the official GitHub CLI instructions, then restart the extension host after PATH changes and Refresh. It never installs or upgrades gh automatically. There is no workspace executable-path setting or workspace identity configuration.

Restricted Mode and virtual workspaces are unsupported. Workspace Trust is required because the extension runs an external executable and interactive task terminals. Commands also check trust before performing operations.

The extension declares extensionKind: ["workspace"]. In a local workspace it manages the local extension host’s gh accounts. With SSH, WSL, Dev Containers, or Codespaces, it runs on that remote extension host and manages that host’s gh configuration, environment, and credential store, not necessarily those on your desktop. Install gh and the extension on the appropriate host. The view and status tooltip identify whether the extension host is local or remote. VS Code Web without a Node extension host is unsupported.

No runtime dependencies, telemetry, backend, paid service, token collection, credential persistence, credential-file reading, Git configuration writes, or SSH-key operations are implemented by this extension. It never calls gh auth token, never requests token-revealing status output, and never logs raw authentication output, subprocess stderr, or environment values. Real user-initiated gh login/switch/logout in an installed production extension necessarily change gh’s own authentication configuration; gh controls its credential storage, browser flow, and terminal output. Login’s device code is visible only in gh’s interactive terminal. Only gh contacts GitHub; account inspection itself can perform authentication/network checks.

Build and develop safely

Use Node.js 22.7+ (24 recommended) and npm. All dependencies are development-only; package-lock.json pins the build tools. The test runner disables process isolation so mocked APIs can run without child test processes.

npm ci --ignore-scripts --cache .npm-cache
npm run compile
npm run lint
npm test
npm run package

Packaging runs compilation, linting, mocked tests, and the prepublish compile, and produces gh-accounts-0.1.0.vsix. vscode:prepublish is VS Code’s build hook; this script does not publish the extension. VSIX contains compiled runtime code, README, license, and the Activity Bar icon, excluding build dependencies, tests, development fixture, caches, and source maps. Complete TypeScript source remains in this directory.

Open this gh-accounts folder in VS Code, then press F5 with GH Accounts (safe mocked demo) selected. Development and test Extension Hosts always use in-memory mocked accounts, even when launched without the included configuration. All switches/logouts remain in memory. Add Account runs only the harmless Node fixture dev/mock-login.cjs in a dedicated terminal, then adds demo-added to the in-memory list. ELECTRON_RUN_AS_NODE is set only for this mock fixture so the VS Code executable can run it as Node. Reloading resets the demo accounts. Real gh is never constructed in development/test mode.

To inspect error conditions, the automated tests inject fake CLI responses and native API stand-ins. They never invoke installed gh or inspect authentication, Git, SSH, or credential files. Tests cover multiple hosts/accounts, health with successful exit, missing/incompatible gh, malformed output, failed switching, logout cancellation, token precedence, serialization, stale refresh protection, timeout/cancellation, command/terminal behavior, and development-mode isolation.

Verification

See the included CHECKS.md for performed checks and the Extension Development Host checklist awaiting manual verification. Automated mocks verify the command contracts and UI model, not native rendering, actual browser login, OS credential-store behavior, or live GitHub/Enterprise interoperability. No real authentication operation or GUI installation is part of these development checks.

Official contracts checked

• gh auth status: --json hosts; JSON can exit zero when accounts are unhealthy.
• CLI auth status implementation and JSON schema: hosts maps hostnames to entry arrays with host, login, active, state, error, and tokenSource; empty/unknown logins can occur for unhealthy environment identities. The parser whitelists safe fields and preserves separate saved and environment entries with the same username.
• gh auth switch, gh auth logout, and gh auth login: explicit host/user arguments, local logout semantics, web login and SSH-key skip flag.
• gh environment: host-specific token precedence.
• VS Code Tree View API, native API reference, and Task Provider guide: native view/commands/status/Quick Pick, ProcessExecution, dedicated presentation, process/task completion events.
• Workspace Trust and remote extensions: trust gating and workspace extension-host placement.