https://github.com/scaryrawr/gh-ado-codespaces
An azure cli identity wrapper for use with GitHub Codespaces
https://github.com/scaryrawr/gh-ado-codespaces
azure-devops gh-extension gh-extensions
Last synced: 4 months ago
JSON representation
An azure cli identity wrapper for use with GitHub Codespaces
- Host: GitHub
- URL: https://github.com/scaryrawr/gh-ado-codespaces
- Owner: scaryrawr
- Created: 2025-05-14T00:01:56.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-14T04:07:25.000Z (4 months ago)
- Last Synced: 2026-02-14T11:47:06.929Z (4 months ago)
- Topics: azure-devops, gh-extension, gh-extensions
- Language: Go
- Homepage:
- Size: 5.43 MB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# gh-ado-codespaces
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.
## Overview
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:
1. Securely forwarding your local Azure CLI credentials to your codespace
2. Automatically detecting and forwarding application ports from your codespace to your local machine
3. Enabling browser opening from your codespace to your local browser
4. Providing command completion notifications to your local desktop
5. Providing a seamless development experience with GitHub Codespaces and Azure DevOps
## Requirements
- [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated
- [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli) (`az`) installed and logged in to the appropriate tenant
- A GitHub Codespace with [Artifacts Helper](https://github.com/microsoft/codespace-features/tree/main/src/artifacts-helper) configured
## Installation
```fish
gh extension install scaryrawr/gh-ado-codespaces
```
## Usage
Before using the extension, make sure you're logged into Azure CLI with the appropriate scope:
```fish
az login --scope 499b84ac-1321-427f-aa17-267ca6975798/.default
```
Then, start a new session with your codespace:
```fish
gh ado-codespaces
```
The extension will:
1. Start a local authentication service
2. Prompt you to select a GitHub Codespace (if not specified)
3. Establish a secure port forwarding channel for authentication
4. Start an interactive SSH session
5. Automatically forward detected application ports from your codespace
### Command Line Options
```
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)
--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:
```fish
gh ado-codespaces -- -L 3000:localhost:3000
```
### Configuration
The extension can read optional configuration values that are scoped per GitHub login. By default it looks for a JSON file at:
```text
$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 is a JSON object keyed by GitHub login IDs returned by `gh auth switch`. Each account can provide Azure-specific overrides, such as the subscription to use when acquiring tokens via the Azure CLI:
```json
{
"login-id-1": {},
"login-id-2": {
"azure": {
"subscription": "00000000-0000-0000-0000-000000000000"
}
}
}
```
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.
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.
## How It Works
| Feature | Description |
|---|---|
| [Authentication](docs/authentication.md) | Forwards local Azure CLI credentials to your codespace for ADO access |
| [Browser Opening](docs/browser-opening.md) | Opens URLs from your codespace in your local browser |
| [Notifications](docs/notifications.md) | Desktop notifications when long-running commands finish |
| [Port Forwarding](docs/port-forwarding.md) | Automatic bi-directional port forwarding (including local AI services) |
## Testing
Run all tests:
```bash
go test -v ./...
```
See [docs/testing.md](docs/testing.md) for the full test suite overview and additional commands.
## Limitations
- Authentication is tied to your local Azure CLI session
- Initial setup with Artifacts Helper is required in the codespace
## Acknowledgments
This project builds upon the work done in [ADO SSH Auth for GitHub Codespaces](https://github.com/scaryrawr/ado-ssh-auth), adapting it as a GitHub CLI extension with additional functionality.