A GitHub CLI extension that enables Azure DevOps (ADO) authentication with GitHub Codespaces via SSH connections, without requiring VS Code to be running. It also provides automatic port forwarding capabilities.
When working with GitHub Codespaces and Azure DevOps services, authentication can be challenging, especially when connecting via SSH rather than through VS Code. This extension bridges that gap by:
- Securely forwarding your local Azure CLI credentials to your codespace
- Automatically detecting and forwarding application ports from your codespace to your local machine
- Enabling browser opening from your codespace to your local browser
- Providing command completion notifications to your local desktop
- Opening supported terminal tools on your local machine from a Codespace
- Providing a seamless development experience with GitHub Codespaces and Azure DevOps
- GitHub CLI (
gh) installed and authenticated - Azure CLI (
az) installed and logged in to the appropriate tenant - A GitHub Codespace with Artifacts Helper configured
- Herdr installed locally when using
--herdr
gh extension install scaryrawr/gh-ado-codespacesBefore using the extension, make sure you're logged into Azure CLI with the appropriate scope:
az login --scope 499b84ac-1321-427f-aa17-267ca6975798/.defaultThen, start a new session with your codespace:
gh ado-codespacesThe extension will:
- Start a local authentication service
- Prompt you to select a GitHub Codespace (if not specified)
- Establish a secure port forwarding channel for authentication
- Start an interactive SSH session
- Automatically forward detected application ports from your codespace
To use Herdr as the interactive remote client instead of opening an SSH shell:
gh ado-codespaces --herdrThe extension performs the same setup, writes GitHub CLI-generated Codespaces entries to a managed OpenSSH include, and launches Herdr with an internal session-specific SSH host alias for the selected Codespace. Keep the extension process running while using Herdr because the authentication, browser, notification, and port-forwarding services are local to that process.
Usage:
gh ado-codespaces [flags] [-- ssh-flags...]
Flags:
--codespace, -c string Name of the codespace
--config Write OpenSSH configuration to stdout
--debug, -d Log debug data to a file
--debug-file string Path of the file to log to
--azure-subscription-id string Azure subscription ID to use for authentication (persisted per GitHub account)
--herdr Connect with Herdr instead of an interactive SSH session
--profile string Name of the SSH profile to use
--repo, -R string Filter codespace selection by repository name (user/repo)
--repo-owner string Filter codespace selection by repository owner (username or org)
--server-port int SSH server port number (0 => pick unused)
You can also pass additional SSH flags after --, for example:
gh ado-codespaces -- -L 3000:localhost:3000Arguments after -- are not supported with --herdr because Herdr owns the SSH invocation.
The --profile and --server-port options are also unavailable in Herdr mode because GitHub CLI cannot combine them with generated OpenSSH configuration.
Herdr mode uses gh codespace ssh --config to maintain reusable host entries under ~/.ssh/gh-ado-codespaces/. The extension adds idempotent Include lines to ~/.ssh/config; it does not replace existing SSH configuration. Dynamic forwarding settings are stored in a session file and removed when the extension exits.
You can combine Herdr mode with the existing selection filters:
gh ado-codespaces --herdr --repo owner/repository
gh ado-codespaces --herdr --codespace codespace-namegh ado-codespaces agent serve starts an NDJSON supervisor on stdin and stdout. Local Copilot extensions and other clients can use it to manage Copilot agents inside Codespaces.
The supervisor supports these operations:
- List, inspect, start, and stop Codespaces.
- Start one or more remote Copilot agents.
- Send prompts and receive ordered agent events.
- Inspect and stop each agent without stopping its Codespace.
Each agent holds a cross-process lease for its Codespace and working directory. A second supervisor cannot start another agent in the same location until the first agent stops.
Agent mode requires the Copilot CLI in the Codespace. Your GitHub CLI token also needs the codespace scope:
gh auth refresh -h github.com -s codespaceProtocol stdout contains NDJSON only. Diagnostics use stderr. Clients must send a shutdown request before closing the process.
When the host has a non-empty DISPLAY environment variable, interactive sessions automatically add trusted X11 forwarding with -Y. Trusted forwarding lets codespace applications access the local X server, so use it only with codespaces you trust. Install and start an X11 server on the host first (for example, XQuartz on macOS).
To disable X11 forwarding for a session, pass -x after the separator:
gh ado-codespaces -- -xThe extension can read optional configuration values that are scoped per GitHub login. By default it looks for a JSON file at:
$OS_CONFIG_DIR/gh-ado-codespaces/config.json
Set the GH_ADO_CODESPACES_CONFIG environment variable to point at a different file if you prefer a custom location.
The configuration file supports global settings plus per-account overrides keyed by your authenticated GitHub username (the .login value returned by gh api user --jq .login):
{
"reversePortForward": [
{ "port": 8081, "description": "Custom service", "enabled": true }
],
"accounts": {
"login-id-1": {},
"login-id-2": {
"azure": {
"subscription": "00000000-0000-0000-0000-000000000000"
},
"reversePortForward": [
{ "port": 9090, "description": "Account-only service", "enabled": true }
]
}
}
}If a subscription is set, the extension requests tokens from the Azure CLI using that subscription. When no override is present, the Azure CLI's default subscription continues to be used.
reversePortForward entries are merged in this order: built-in defaults, top-level config, then per-account config. Matching ports are overridden by later entries, so you can disable or update defaults per account.
You can create or update this setting directly from the command line by supplying the --azure-subscription-id flag once. The value will be persisted for the active GitHub login so future invocations do not need the flag unless you want to change or clear it. To clear the stored value, edit the config file and remove (or empty) the subscription field for your login.
| Feature | Description |
|---|---|
| Authentication | Forwards local Azure CLI credentials to your codespace for ADO access |
| Browser Opening | Opens URLs from your codespace in your local browser |
| Notifications | Desktop notifications when long-running commands finish |
| Port Forwarding | Automatic bi-directional port forwarding (including local AI services) |
| Terminal tools | Opens supported local terminal tools from the Codespace |
| xdg-open shim | Intelligent file and URL opener for SSH / tmux environments |
gh ado-codespaces automatically installs an xdg-open shim into the codespace at /usr/local/bin/xdg-open. No configuration is needed.
The shim replaces the standard xdg-open and routes each request based on what is being opened and how you are connected.
URLs (http://, https://, mailto:, ftp://) are forwarded through the following chain, stopping at the first success:
- The gh-ado browser socket (the same service that powers browser opening)
$BROWSER, if setcode --open-url(VS Code remote)- The real
/usr/bin/xdg-open
Files are opened with a viewer chosen by file type:
| Type | Viewer |
|---|---|
| Images (jpg, png, gif, …) | chafa |
| PDFs | pdftotext + less, or pdfinfo |
| Markdown | glow, then bat, then $EDITOR |
| Everything else | $EDITOR, then vi |
The viewer is launched in whichever environment is active:
- Inside tmux — opens in a new vertical split pane. Editors (vim, nvim, …) open directly; non-interactive viewers (chafa, bat, …) pause with a "press enter" prompt so you can read the output.
- SSH without tmux — runs the viewer inline in the current terminal (blocking).
- Not in SSH — delegates to the real
/usr/bin/xdg-openor VS Code, falling back to the inline viewer.
Run all tests:
go test -v ./...See docs/testing.md for the full test suite overview and additional commands.
- Authentication is tied to your local Azure CLI session
- Initial setup with Artifacts Helper is required in the codespace
- Herdr mode requires the system OpenSSH client to honor
~/.ssh/config
This project builds upon the work done in ADO SSH Auth for GitHub Codespaces, adapting it as a GitHub CLI extension with additional functionality.