Skip to content

Platform Bridge - Legacy Multi-Platform Support

Compatibility note: this page documents the legacy platform bridge. New default-workflow provider behavior is specified by the provider-neutral workflow API. Recipes should call amplihack workflow ... --format json helpers, not this bridge directly. Azure Repos pull-request publication is manual in the provider-neutral workflow contract.

Legacy automatic platform detection and unified interface fer selected GitHub and Azure DevOps operations.

Quick Start

The legacy bridge can detect whether yer repository be hosted on GitHub or Azure DevOps and use matching CLI tools. New workflow code should use the provider-neutral helpers instead.

from claude.tools.platform_bridge import PlatformBridge

# Automatically detects platform from git remote
bridge = PlatformBridge()

# Create an issue/work item
issue = bridge.create_issue(
    title="Add authentication",
    body="Implement JWT authentication"
)

# Create a draft pull request through the legacy bridge only.
# default-workflow does not automate Azure Repos PR creation.
pr = bridge.create_draft_pr(
    title="feat: Add JWT auth",
    body="Implementation of authentication system",
    source_branch="feat/auth",
    target_branch="main"
)

What Problem Does This Solve?

Before the platform bridge, the legacy DEFAULT_WORKFLOW.md hardcoded GitHub-specific commands (gh issue create, gh pr create) throughout all 22 steps. This meant:

  • Azure DevOps users couldn't use the workflow without manual workarounds
  • Every workflow step required platform-specific instructions
  • Switching between GitHub and Azure DevOps projects required different workflows

The legacy platform bridge solved this by:

  • Automatic Detection: Examines git remote URLs to determine platform
  • Unified Interface: Single API that works fer both GitHub and Azure DevOps
  • Zero Configuration: Works without user intervention or config changes
  • Graceful Fallback: Clear error messages when CLI tools be missin'

Core Capabilities

The platform bridge supports provider operations used by older workflow tooling. Provider-neutral workflow helpers supersede this direct bridge for default-workflow.

Operation GitHub Command Azure DevOps Command Workflow Step
Create Issue gh issue create az boards work-item create Step 3
Create Draft PR gh pr create --draft Legacy bridge only; not part of provider-neutral default-workflow GitHub adapter only for automated workflow publication; AzDO manual action
Mark PR Ready gh pr ready Legacy bridge only GitHub adapter only for automated workflow paths
Add PR Comment gh pr comment Legacy bridge only GitHub adapter only for automated workflow paths
Check CI Status gh pr checks Legacy bridge only GitHub adapter only for automated workflow paths

How Platform Detection Works

The platform bridge examines yer git remote URLs to determine the platform:

# Detects GitHub
git remote -v
# origin  https://github.com/owner/repo.git (fetch)
# → Platform: github

# Detects Azure DevOps
git remote -v
# origin  https://dev.azure.com/org/project/_git/repo (fetch)
# → Platform: azdo

Detection Logic:

  1. Runs git remote -v to get all remotes
  2. Checks origin remote first (most common)
  3. Falls back to first available remote if origin doesn't exist
  4. Examines URL patterns:
  5. github.com → GitHub
  6. dev.azure.com or visualstudio.com → Azure DevOps
  7. Raises clear error if platform cannot be determined

Prerequisites

Ye need the appropriate CLI tools installed fer yer platform:

For GitHub repositories:

# Install GitHub CLI
brew install gh  # macOS
# OR
sudo apt install gh  # Ubuntu/Debian

For Azure DevOps repositories:

# Install Azure CLI
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash  # Ubuntu/Debian
# OR
brew install azure-cli  # macOS

Ye don't need both CLIs installed - only the one fer yer current repository's platform.

Usage Examples

Creating an Issue/Work Item

from claude.tools.platform_bridge import PlatformBridge

bridge = PlatformBridge()

# Works on both GitHub and Azure DevOps
issue = bridge.create_issue(
    title="Implement feature X",
    body="Detailed description here"
)

print(f"Created: {issue['url']}")
# GitHub: https://github.com/owner/repo/issues/42
# Azure DevOps: https://dev.azure.com/org/project/_workitems/edit/42

Creating a Draft Pull Request

# Create draft PR (both platforms)
pr = bridge.create_draft_pr(
    title="feat: Add new feature",
    body="## Summary\n\nImplementation details...",
    source_branch="feat/new-feature",
    target_branch="main"
)

print(f"Draft PR created: {pr['url']}")

Marking PR Ready for Review

# Mark PR as ready (removes draft status)
result = bridge.mark_pr_ready(pr_number=42)

if result['success']:
    print("PR is now ready fer review!")

Adding Comments to PR

# Add comment to PR
comment = bridge.add_pr_comment(
    pr_number=42,
    comment="All tests be passin' - ready fer merge!"
)

Checking CI Status

# Check CI pipeline status
status = bridge.check_ci_status(pr_number=42)

if status['all_passing']:
    print("All checks passed!")
else:
    print(f"Failed checks: {status['failed_checks']}")

Error Handling

The platform bridge provides clear, actionable error messages:

try:
    bridge = PlatformBridge()
except PlatformDetectionError as e:
    # Could not determine platform from git remotes
    print(f"Platform detection failed: {e}")

try:
    issue = bridge.create_issue(title="Test", body="Body")
except CLIToolMissingError as e:
    # GitHub CLI or Azure CLI not installed
    print(f"Missing tool: {e}")
    print(f"Install with: {e.install_command}")

Common Error Scenarios:

  1. No Git Remote: Repository has no remotes configured

  2. Error: "No git remotes found. Add a remote with git remote add origin <url>"

  3. Unknown Platform: Remote URL doesn't match GitHub or Azure DevOps patterns

  4. Error: "Could not detect platform from remote URL: "

  5. Missing CLI Tool: Required CLI not installed

  6. Error: "GitHub CLI not found. Install with: brew install gh"

  7. Authentication Required: CLI tool not authenticated

  8. Error: "GitHub CLI not authenticated. Run: gh auth login"

Integration with default-workflow

The platform bridge is integrated into the default-workflow skill/recipe at these steps:

Step 3: Create Issue/Work Item

# Platform-agnostic issue creation
bridge = PlatformBridge()
issue = bridge.create_issue(title=title, body=body)

Step 15: Create Draft PR

# Works on both GitHub and Azure DevOps
pr = bridge.create_draft_pr(
    title=pr_title,
    body=pr_body,
    source_branch=current_branch,
    target_branch="main"
)

Step 20: Mark PR Ready

# Remove draft status
bridge.mark_pr_ready(pr_number=pr_number)

Step 21: Check CI Status

# Platform-agnostic CI status check
status = bridge.check_ci_status(pr_number=pr_number)
if not status['all_passing']:
    print("CI checks still runnin' or failed")

Architecture

The platform bridge follows the Brick Philosophy - a self-contained module with clear public contract:

.claude/tools/platform_bridge/
├── __init__.py              # Public API via __all__
├── detector.py              # Platform detection logic
├── operations.py            # PlatformOperations interface
├── github_bridge.py         # GitHub implementation
├── azdo_bridge.py          # Azure DevOps implementation
├── exceptions.py            # Custom exceptions
├── tests/                   # Unit tests
│   ├── test_detector.py
│   ├── test_github.py
│   └── test_azdo.py
└── README.md               # This file

Public API (__all__):

  • PlatformBridge - Main entry point
  • detect_platform() - Standalone detection function
  • PlatformDetectionError - Exception fer detection failures
  • CLIToolMissingError - Exception fer missing CLI tools

Security Considerations

The platform bridge delegates authentication to official CLI tools:

  • GitHub: Uses gh CLI authentication (gh auth login)
  • Azure DevOps: Uses az CLI authentication (az login)

Input Validation:

  • All subprocess calls use parameterized commands (no shell injection)
  • Branch names, titles, and bodies be validated before passin' to CLI
  • URL parsing uses standard library urllib.parse

Subprocess Safety:

  • Timeouts on all subprocess calls (default 30 seconds)
  • Standard error captured and parsed
  • Exit codes checked before processin' output

See Security Documentation fer complete security analysis.

Troubleshooting

Platform Detection Fails

Problem: PlatformDetectionError: Could not detect platform

Solutions:

  1. Check git remotes: git remote -v
  2. Ensure remote URL contains github.com or dev.azure.com
  3. Add remote if missin': git remote add origin <url>

CLI Tool Not Found

Problem: CLIToolMissingError: GitHub CLI not found

Solutions:

  1. Install the required CLI tool (see Prerequisites)
  2. Verify installation: gh --version or az --version
  3. Ensure CLI be in yer PATH

Authentication Errors

Problem: CLI commands fail with authentication errors

Solutions:

  1. GitHub: Run gh auth login and follow prompts
  2. Azure DevOps: Run az login and authenticate
  3. Verify authentication: gh auth status or az account show

Wrong Platform Detected

Problem: Bridge detects wrong platform

Solutions:

  1. Check which remote be detected: git remote -v
  2. Ensure origin points to correct URL
  3. Platform detection prioritizes origin over other remotes

See Also