GitHub Copilot Home Assistant Integration

Key Features

Installation

Requires Home Assistant 2025.2.4 or later. Use a current stable release for Home Assistant's built-in MCP server.

Via HACS (Recommended)

1. Open HACS in Home Assistant.
2. Go to Integrations and click the + button.
3. Search for GitHub Copilot.
4. Click Install, then restart Home Assistant.
5. Configure via Settings → Devices & Services → Add Integration.

Manual Installation

1. Copy the custom_components/github_copilot directory to your Home Assistant custom_components directory.
2. Restart Home Assistant.
3. Configure via Settings → Devices & Services → Add Integration.

GitHub Copilot Bridge Add-on

The GitHub Copilot Bridge add-on runs the CLI in a dedicated container that the integration connects to over the internal network. Add-on v3.12.2 uses CLI v1.0.83, matching the integration's SDK 1.0.13.

Add-on Highlights

• 🐳 Containerized Copilot CLI server on port 8000 (internal network only)
• 🔄 Automatic retry mechanism — up to 5 restart attempts on failures
• 🔐 Token-based authentication via environment variables (no interactive prompts)
• 🏗️ Multi-architecture support: amd64 and aarch64
• ✅ SHA256 checksum verification for CLI binary integrity
• 🛡️ Clear configured-token status, with authentication checked by SDK clients

Installing the Add-on

1. Go to Settings → Add-ons → Add-on Store.
2. Click the ⋮ menu and choose Repositories.
3. Add: https://github.com/tserra30/Github-Copilot-SDK-integration
4. Find GitHub Copilot Bridge in the store and click Install.
5. In the add-on Configuration tab, set your fine-grained GitHub token with Account permissions → Copilot Requests → Read and write:

   github_token: "<GITHUB_FINE_GRAINED_PAT>"
   mcp_config: ""

6. Start the add-on and check the Log tab to confirm success.

Configure MCP in the integration's MCP field, even when using the bridge. The add-on's optional mcp_config is available to other bridge clients but does not authorize tools for this integration.

Finding the Add-on URL

The integration connects to the add-on via its internal hostname (shown in the add-on Info tab). The URL format is:

http://<hostname>:8000
# Example:
http://a1b2c3d4-github-copilot-bridge:8000

Note: Home Assistant generates the hostname from the add-on slug by replacing all underscores (_) with hyphens (-). Always use hyphens — using underscores will cause DNS resolution to fail.

Configuration

1. Go to Settings → Devices & Services → Add Integration.
2. Search for GitHub Copilot and select it.
3. Fill in the fields:
   • GitHub Token — Fine-grained personal access token with Copilot Requests permission. Required in local mode; optional with a bridge URL because the bridge manages authentication.
   • Model — Defaults to auto for new setups; custom model IDs are also accepted. Existing saved choices are preserved.
   • Copilot CLI URL (optional) — URL of the bridge, e.g. http://a1b2c3d4-github-copilot-bridge:8000. Leave empty for local mode, where the SDK downloads a matching runtime if no installed or explicit executable is available.
   • MCP configuration (optional) — Inline JSON containing mcpServers, or a JSON file path readable by Home Assistant Core, optionally prefixed with @.

Getting a GitHub Token

1. Ensure you have an active GitHub Copilot subscription.
2. Generate a fine-grained PAT from GitHub token settings.
3. Grant Account permissions → Copilot Requests → Read and write. Repository permissions are not required.
4. Keep the token secure — never share it publicly.

Classic PATs are not a supported fallback. Keep the GitHub token separate from the Home Assistant long-lived token used for MCP.

Home Assistant MCP Setup

1. Add Model Context Protocol Server under Settings → Devices & services, enable its Assist API, and expose a safe test helper to Assist.
2. Create a Home Assistant long-lived access token in your profile's security settings.
3. Set the following in the GitHub Copilot integration's MCP configuration field (not just the add-on options):

{
  "mcpServers": {
    "homeassistant": {
      "type": "http",
      "url": "http://homeassistant:8123/api/mcp",
      "tools": ["*"],
      "headers": {
        "Authorization": "Bearer <HOME_ASSISTANT_TOKEN>"
      }
    }
  }
}

The URL must be reachable from the Copilot CLI runtime; homeassistant is appropriate on the bridge's internal network. Other deployments need an appropriate reachable address. No external MCP server or proxy is needed.

Every server requires an explicit tools list. Use [] to disable tools, named tools for limited access, or ["*"] to authorize all current and future tools on a trusted server. Allowed calls execute without confirmation. Built-in CLI tools and unconfigured MCP access are denied.

Missing tools, invalid JSON, unreadable files, and invalid server definitions produce errors during setup and options changes. Older configurations without a tools list must be updated explicitly. Protect MCP headers and files as credentials, and verify actual helper state changes rather than relying only on a model's success message.

See the README's MCP configuration guide for details.

Example Automation

automation:
  - alias: "Morning briefing with Copilot"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: conversation.process
        data:
          text: "Good morning! What should I know today?"
          agent_id: conversation.github_copilot

Supported Models

New setups default to auto. Open Settings → Devices & services → GitHub Copilot → Configure to fetch the runtime's live model catalog and select an available model.

Existing selections are not silently replaced on upgrade. If an older ID such as gpt-4.1 produces Model not available, choose a currently supported model through Configure.

Troubleshooting

"Unable to connect to Copilot CLI"

If bridge v3.12.0 says it is listening but Home Assistant reports connection refused, upgrade the bridge to v3.12.1. This fixes its loopback-only listener without publishing port 8000 to the host. The bridge is updated separately from the HACS integration.

This means the Copilot CLI is not reachable. Two options:

• Option A (Recommended) — Install and start the GitHub Copilot Bridge add-on, then enter its URL in the Copilot CLI URL field.
• Local mode — Leave the CLI URL empty and configure a fine-grained GitHub token in the integration. Check outbound connectivity, a writable SDK runtime cache, and any stale COPILOT_CLI_PATH override.

Authentication Errors

Bridge v3.12.2 reports that a GitHub token is configured without running an unreliable startup probe. The integration checks SDK authentication status and confirms model access with a real response during setup. The separate COPILOT_CONNECTION_TOKEN warning concerns client-to-bridge access, not GitHub credentials. Keep port 8000 on a trusted internal network.

• Verify your fine-grained GitHub token is valid and has Copilot Requests → Read and write permission.
• Ensure your GitHub Copilot subscription is active.
• Try regenerating your personal access token.

Connection and Session Logs

Integration v1.0.8 logs connection and session lifecycle events in Home Assistant logs under custom_components.github_copilot, not in the bridge's Log tab. Enable that logger at info, or temporarily debug for request milestones. Prompts, responses, and credentials are not included in those lifecycle messages. See the logging guide.

SDK Installation Issues (Home Assistant OS)

Home Assistant installs the official github-copilot-sdk==1.0.13 from PyPI in both modes. Its universal py3-none-any wheel supports Home Assistant Core's Alpine/musl container; no custom wheel is required.

In local mode, the SDK automatically downloads and verifies a checksummed matching CLI runtime when no installed or explicit executable is available. SDK 1.0.13 pins CLI 1.0.83, with musl and glibc builds for amd64/arm64. In remote bridge mode, no local CLI binary or runtime download is needed. Update the bridge alongside the integration.

Slow Responses

• Choose an available faster model through Configure, or increase the response timeout there.
• Check your network latency.
• Reduce concurrent requests.

For more help, open an issue on GitHub.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on how to propose changes, run the linter, and submit pull requests.