Set Up GitHub BYO App Connector

Connect your agent to GitHub using a Bring Your Own GitHub App — a service identity registered by your organization that signs authentication requests with an RSA key in Azure Key Vault.

What you'll build

App-based access to your GitHub repositories using a BYO GitHub App and a non-exportable Key Vault signing operation. All operations are attributed to your App identity, not an individual user. Learn more → GitHub Connector.

---

When to use BYO App

Use BYO App when:

• Your organization requires app-based auth and key custody controls.
• You are connecting *.ghe.com repositories (required).
• You want installation-token based access rather than user tokens.

Prerequisites

• Running agent with Administrator or Standard User role
• A GitHub App created on your target host (github.com or *.ghe.com)
• GitHub org or repository admin access (to create/install or verify GitHub App scope)
• App private key imported into Azure Key Vault as an RSA key with the Sign operation enabled
• Agent system-assigned identity, or a user-assigned identity attached to the agent, with Key Vault Crypto User on the key or vault

Step 1: Create a GitHub App

If you already have a GitHub App with the right permissions, skip to Step 2.

1. Go to your GitHub host:
   • github.com → navigate to your org → Settings → Developer settings → GitHub Apps → New GitHub App
   • <tenant>.ghe.com → same path on your GHE instance
2. Fill in the app details:
   • GitHub App name: e.g., contoso-sre-agent-reader (prefix with your org name to avoid conflicts)
   • Homepage URL: https://sre.azure.com
   • Webhook: Uncheck Active (the agent does not use webhooks)
3. Under Permissions, set:
   • Repository permissions → Contents: Read-only (required)
   • Repository permissions → Metadata: Read-only (auto-selected)
   • Optionally add Issues and Pull requests read access
4. Under Where can this GitHub App be installed?, select Only on this account
5. Click Create GitHub App
6. Note the Client ID shown on the App settings page (starts with Iv... — this is different from the numeric App ID)

Step 1b: Install the GitHub App

1. On the GitHub App settings page, click Install App in the left sidebar
2. Select your organization
3. Choose All repositories or select specific repos
4. Click Install

Step 2: Generate a private key

1. On the GitHub App settings page, scroll to Private keys
2. Click Generate a private key
3. A .pem file downloads — this is the RSA private key the agent uses to authenticate

Keep the PEM safe

You'll import this file into Key Vault in the next step. Don't commit it to a repository or share it. Securely delete the local file after confirming the import.

Step 3: Import the private key into Key Vault

1. Open the Azure portal and navigate to your Key Vault.
2. Go to Keys → Generate/Import.
3. Set Options to Import, enter a Name (for example, sre-agent-github-app-key), and upload the .pem file generated by GitHub.
4. Under Permitted operations, enable Sign, then select Create.
5. Open the imported key and copy its Key Identifier URI:

https://myvault.vault.azure.net/keys/sre-agent-github-app-key

Versioned vs unversioned URI

Both .../keys/<name> and .../keys/<name>/<version> are accepted. Use the unversioned URI to resolve the current key version. When rotating the key, coordinate the GitHub App key and the Key Vault key version so they continue to represent the same key pair.

Step 4: Grant Key Vault access to agent identity

1. In Azure portal, open the Key Vault or imported key, then open Access control (IAM).
2. Assign Key Vault Crypto User to the identity that the agent will use for this GitHub App:
   • Use the agent's system-assigned managed identity for the default configuration.
   • Use a user-assigned managed identity attached to the agent for per-App isolation.
3. Wait for role assignment propagation.

The role can be scoped to the imported key. If you assign it at vault scope, the identity can perform cryptographic operations with other keys in that vault as allowed by the role.

Step 5: Configure BYO App in Code Access

1. Open your agent.

2. Navigate to Context → Code Access.

3. Click Add repositories.

4. Choose GitHub and enter host:

   • github.com for public GitHub
   • <tenant>.ghe.com for Enterprise Cloud

5. Continue to Authenticate.

6. Select Bring your own GitHub App.

7. Enter:

   • Client ID
   • Private key URI (Key Vault) in the form https://<vault>.vault.azure.net/keys/<key-name>
   • Key Vault identity (keep the system-assigned default or select an attached user-assigned identity)

8. Click Connect.

The wizard uses the selected identity to sign a GitHub App JWT in Key Vault, validates the Client ID against the selected GitHub host, and lists repositories available to the App. No private key material is returned to the agent.

Checkpoint

If you see the green checkmark and "Connected as GitHub App", your credentials are valid. If Connect fails, verify your Client ID, Key Vault URI, and managed identity permissions.

If Code Access does not open from left navigation, refresh the agent page, expand Context again, and retry.

GitHub Enterprise Cloud hosts

When you enter a *.ghe.com domain as the host, the wizard automatically selects Bring your own GitHub App — OAuth and PAT are not available for GHE hosts.

Step 6: Add repositories and verify

1. Select repositories and save.

2. Confirm the Code Access card shows the connected host, auth type GitHubApp, and a healthy connection.

3. Test code access in chat:

What files are in the root of owner/repo?

If you also granted Issues permission to your GitHub App, verify issue operations:

List recent issues from owner/repo.

Per-App managed identity

By default, the agent uses its system-assigned managed identity to ask Key Vault to sign GitHub App JWTs. If you manage multiple GitHub Apps (for example, one per GHE instance), you can assign a different user-assigned managed identity to each App. This provides security isolation — each identity only has signing access to its own Key Vault key.

Select the identity in the Key Vault identity dropdown during Step 5.

Multi-host support

You can connect multiple GitHub hosts to the same agent. Each host has independent auth:

• github.com → OAuth, PAT, or BYO App
• contoso.ghe.com → BYO App
• engineering.ghe.com → BYO App (with a different GitHub App)

Disconnecting one host does not affect others.

Troubleshooting

Symptom	Likely cause	Fix
Auth validation fails	Wrong Client ID or wrong host	Verify app was created on the same host entered in Code Access
Key Vault signing fails	Wrong key URI, non-RSA key, Sign is disabled, or the selected identity lacks permission	Use a /keys/<name> URI, verify the imported key is RSA with Sign enabled, and grant Key Vault Crypto User to the selected identity
App connects but the repository is not listed	App is not installed on the repository	Update the GitHub App installation and include the repository
Repo shows Failed in Code Access	Missing app permissions or install scope	Verify Metadata: Read + Contents: Read and installation scope
Chat issues work but Code Access fails	Endpoint/path checks differ	Re-run connection test and verify metadata permission

What you learned

• Your agent now authenticates to GitHub using a service identity (GitHub App) instead of a personal token
• The private key stays in Azure Key Vault — the agent requests signatures using managed identity
• Tokens are short-lived and auto-refreshed — no manual rotation needed
• BYO App works for both github.com and *.ghe.com hosts
• You can assign a different managed identity per GitHub App for security isolation

Related

Resource	Purpose
GitHub Connector	Compare all connection types and auth methods
Set Up GitHub Connector (OAuth or PAT)	OAuth/PAT auth for github.com
Set Up MCP Connector	GitHub via MCP tools