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 with Key Vault-backed credentials.

What you'll build

App-based access to your GitHub repositories using a BYO GitHub App with Key Vault-backed credentials. 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 stored in Azure Key Vault as a secret
• Agent managed identity with Key Vault Secrets User on that 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 upload this to Key Vault in the next step. Don't commit it to a repository or share it.

Step 3: Store private key in Key Vault

1. Open the Azure portal and navigate to your Key Vault.
2. Go to Secrets → Generate/Import.
3. Set Name (e.g., sre-agent-github-app-key) and paste the full PEM content as the Value (including -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY----- headers).
4. Click Create.
5. Open the secret, click the current version, and copy the Secret Identifier URI:

https://myvault.vault.azure.net/secrets/my-github-app-key/<version>

Versioned vs unversioned URI

You can use the versioned URI (with /<version> suffix) to pin to a specific key version, or omit the version to always use the latest. Unversioned is recommended — when you rotate the key, the agent automatically picks up the new version without updating the URI.

Step 4: Grant Key Vault access to agent identity

1. In Azure portal, open Key Vault -> Access control (IAM).
2. Assign Key Vault Secrets User to the agent managed identity.
3. Wait for role assignment propagation.

Step 5: Configure BYO App in Code Access

1. Open your agent.
2. Navigate to Builder -> 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 secret URI (Key Vault)
   • Optional Key Vault identity (or keep system-assigned)
8. Click Connect.

The wizard validates your credentials. When successful, you'll see Connected as GitHub App with a green checkmark.

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 Builder 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 Code Access card shows connected host and auth type GitHubApp.

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 read the private key from Key Vault. If you manage multiple GitHub Apps (e.g., one per GHE instance), you can assign a different user-assigned managed identity to each App. This provides security isolation — each identity only has access to its own Key Vault secret.

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
Secret read fails	Missing Key Vault RBAC or access policy	Grant Key Vault Secrets User to agent identity. If using Key Vault access policies, grant Get permission on secrets.
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 reads it at runtime 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