Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 8 additions & 1 deletion hub/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,14 @@ SCHEDULED_JOB_CONCURRENCY=1
# AZURE_STORAGE_CONTAINER=artifacts
# AZURE_CLIENT_ID=your-user-assigned-managed-identity-uuid

# Optional simple/local Copilot credential provider. No production provider is configured by default.
# Optional Copilot credential provider. No provider is configured by default.
# Organization-billed GitHub App installation:
# REPLICA_COPILOT_AUTHENTICATION=github-app-installation
# GITHUB_APP_ID=
# GITHUB_APP_PRIVATE_KEY=
# REPLICA_COPILOT_GITHUB_ORGANIZATION=
# REPLICA_COPILOT_GITHUB_INSTALLATION_ID=
# Simple/local providers:
# REPLICA_COPILOT_AUTHENTICATION=ambient-cli
# Or use environment-token together with the secret below:
# REPLICA_COPILOT_AUTHENTICATION=environment-token
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ describe("copilotConnectionStatusSchema", () => {
configured: true,
connected: false,
savedConnection: true,
credentialIdentity: null,
connectedBy: null,
refusedAt: "2026-11-11T13:00:00.000Z",
verifiedAt: null,
Expand All @@ -17,6 +18,7 @@ describe("copilotConnectionStatusSchema", () => {
configured: true,
connected: false,
savedConnection: true,
credentialIdentity: null,
connectedBy: null,
refusedAt: "2026-11-11T13:00:00.000Z",
verifiedAt: null,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,15 @@ export const copilotConnectionStatusSchema = z
configured: z.boolean(),
connected: z.boolean(),
savedConnection: z.boolean(),
credentialIdentity: z
.object({
appId: z.string().regex(/^[1-9]\d*$/),
installationId: z.string().regex(/^[1-9]\d*$/),
organization: z.string().min(1).max(39),
})
.strict()
.nullable()
.default(null),
connectedBy: z
.object({
login: z.string().nullable(),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ describe("copilotConnectionPageData()", () => {
configured: false,
connected: false,
savedConnection: false,
credentialIdentity: null,
connectedBy: null,
refusedAt: null,
verifiedAt: null,
Expand All @@ -34,6 +35,7 @@ describe("copilotConnectionPageData()", () => {
configured: true,
connected: false,
savedConnection: false,
credentialIdentity: null,
connectedBy: null,
refusedAt: null,
verifiedAt: null,
Expand All @@ -53,6 +55,7 @@ describe("copilotConnectionPageData()", () => {
configured: true,
connected: true,
savedConnection: true,
credentialIdentity: null,
connectedBy: {
login: "octocat",
membershipId: session.membershipId,
Expand All @@ -73,6 +76,7 @@ describe("copilotConnectionPageData()", () => {
configured: true,
connected: false,
savedConnection: true,
credentialIdentity: null,
connectedBy: null,
refusedAt: "2026-11-11T13:00:00.000Z",
verifiedAt: null,
Expand All @@ -83,4 +87,26 @@ describe("copilotConnectionPageData()", () => {
expect(data.connect?.label).toBe("Connect Copilot")
expect(data.disconnect?.label).toBe("Disconnect Copilot")
})

it("names the billed organization and GitHub App for installation credentials", () => {
const data = copilotConnectionPageData(session, {
configured: true,
connected: false,
savedConnection: false,
credentialIdentity: {
appId: "123",
installationId: "456",
organization: "github",
},
connectedBy: null,
refusedAt: null,
verifiedAt: null,
})

expect(data.accessDenied).toBe(false)
if (data.accessDenied) throw new Error("The administrator must receive connection controls.")
expect(data.usageLabel).toMatch(/billed to the github organization through GitHub App 123/)
expect(data.connect?.consequence).toMatch(/github organization through GitHub App 123/)
expect([data.usageLabel, data.connect?.consequence].join(" ")).not.toContain("456")
})
})
Original file line number Diff line number Diff line change
Expand Up @@ -34,10 +34,13 @@ export function copilotConnectionPageData(
submitPath: "/settings/copilot",
credentialLabel: status.configured
? null
: "Configure a Copilot credential provider before connecting. Simple deployments can explicitly select ambient CLI authentication or the environment-token provider.",
: "Configure a Copilot credential provider before connecting. Production deployments can use a GitHub App installation; simple deployments can explicitly select ambient CLI authentication or the environment-token provider.",
connectedBy: status.connectedBy
? `${status.connectedBy.login ? `@${status.connectedBy.login}` : "A Hub administrator"} connected Copilot. Membership ${status.connectedBy.membershipId}.`
: undefined,
usageLabel: status.credentialIdentity
? `Copilot usage is billed to the ${status.credentialIdentity.organization} organization through GitHub App ${status.credentialIdentity.appId}. Organization model policy, budget, and installation revocation continue to apply.`
: undefined,
verifiedLabel: status.verifiedAt
? `Copilot last answered on ${new Date(status.verifiedAt).toISOString()}.`
: undefined,
Expand All @@ -52,8 +55,9 @@ export function copilotConnectionPageData(
: status.verifiedAt
? "Check and connect Copilot"
: "Connect Copilot",
consequence:
"Hub asks Copilot to verify the configured credential. Later learning runs may send review comment text without reviewer identity. The available local providers attribute usage to the signed-in account or user-token identity.",
consequence: status.credentialIdentity
? `Hub asks Copilot to verify a fresh credential for the ${status.credentialIdentity.organization} organization through GitHub App ${status.credentialIdentity.appId}. Later learning runs may send review comment text without reviewer identity. The organization's Copilot model policy, budget, and App installation revocation continue to apply.`
: "Hub asks Copilot to verify the configured credential. Later learning runs may send review comment text without reviewer identity. The available local providers attribute usage to the signed-in account or user-token identity.",
confirmLabel: "I understand and confirm connecting Copilot for this Hub.",
verification,
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -113,4 +113,41 @@ describe("securityAuditPageData()", () => {
}),
])
})

it("labels the billed organization and GitHub App identity", () => {
const session = currentHubSessionSchema.parse({
authenticated: true,
membershipId: "11111111-1111-4111-8111-111111111111",
userId: "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
provider: "github",
login: "octocat",
name: "The Octocat",
role: "ADMINISTRATOR",
})
const response = securityAuditResponseSchema.parse({
records: [
{
id: "22222222-2222-4222-8222-222222222222",
occurredAt: "2026-11-10T12:00:00.000Z",
action: "copilot.connection.connected",
outcome: "success",
actor: null,
context: {
appId: "123",
billedOrganization: "github",
provider: "github_app_installation",
phase: "connected",
},
},
],
nextCursor: null,
})

expect(securityAuditPageData(session, response).events[0]?.context).toEqual([
{ label: "GitHub App", value: "123" },
{ label: "Billed organization", value: "github" },
{ label: "Provider", value: "github_app_installation" },
{ label: "Phase", value: "connected" },
])
})
})
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,8 @@ import type { SecurityAuditResponse } from "@application/hub/security-audit-cont
import { administratorWorkspace } from "../administrator-workspace"

const contextLabels: Record<string, string> = {
appId: "GitHub App",
billedOrganization: "Billed organization",
membershipId: "Membership",
operation: "Operation",
phase: "Phase",
Expand Down
32 changes: 31 additions & 1 deletion hub/client/pages/copilot-connection-page/stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -74,12 +74,42 @@ export default meta
type Story = StoryObj<typeof meta>

export const NotConnected: Story = {}
export const OrganizationInstallation: Story = {
args: {
data: {
...data,
usageLabel:
"Copilot usage is billed to the github organization through GitHub App 12345. Organization model policy, budget, and installation revocation continue to apply.",
connect: {
...connect,
consequence:
"Hub asks Copilot to verify a fresh credential for the github organization through GitHub App 12345. Later learning runs may send review comment text without reviewer identity. The organization's Copilot model policy, budget, and App installation revocation continue to apply.",
},
},
},
}
export const ConnectedOrganizationInstallation: Story = {
args: {
data: {
...connected,
Comment thread
alliscode marked this conversation as resolved.
Resolved
notice: "Copilot is connected.",
usageLabel:
"Copilot usage is billed to the github organization through GitHub App 12345. Organization model policy, budget, and installation revocation continue to apply.",
connect: {
...connect,
label: "Check Copilot connection",
consequence:
"Hub asks Copilot to verify a fresh credential for the github organization through GitHub App 12345. Later learning runs may send review comment text without reviewer identity. The organization's Copilot model policy, budget, and App installation revocation continue to apply.",
},
},
},
}
export const NoToken: Story = {
args: {
data: {
...data,
credentialLabel:
"Configure a Copilot credential provider before connecting. Simple deployments can explicitly select ambient CLI authentication or the environment-token provider.",
"Configure a Copilot credential provider before connecting. Production deployments can use a GitHub App installation; simple deployments can explicitly select ambient CLI authentication or the environment-token provider.",
connect: null,
},
},
Expand Down
12 changes: 10 additions & 2 deletions hub/docs/copilot.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,18 @@ A Hub administrator can connect one deployment-wide Copilot credential for learn

## Configure a provider

No Copilot credential provider is enabled by default. Simple and local deployments can explicitly select one:
No Copilot credential provider is enabled by default. Production deployments can select the Hub GitHub App installation:

- `REPLICA_COPILOT_AUTHENTICATION=github-app-installation` uses `GITHUB_APP_ID`, a PEM-encoded `GITHUB_APP_PRIVATE_KEY`, `REPLICA_COPILOT_GITHUB_ORGANIZATION`, and `REPLICA_COPILOT_GITHUB_INSTALLATION_ID`.
- Hub verifies that the App and organization own that installation and that it grants only read-only organization Copilot requests.
- Hub mints a fresh installation token for each learning command and never persists it. Usage is billed to the configured organization and remains subject to its model policy, budget, permission changes, and installation revocation.

Simple and local deployments can instead explicitly select one personal provider:

- `REPLICA_COPILOT_AUTHENTICATION=ambient-cli` uses the Copilot account signed in where Hub runs.
- `REPLICA_COPILOT_AUTHENTICATION=environment-token` reads `REPLICA_COPILOT_TOKEN` from the deployment secret store.

These providers attribute usage to the represented individual identity. Production deployments should supply a governed provider through the same provider boundary. Restart every Hub API and worker process together after changing provider configuration.
The personal providers attribute usage to the represented individual identity. Hub never falls back between credential modes. Restart every Hub API and worker process together after changing provider configuration.

See [Learning foundation](learning-foundation.md) for the command boundary, storage configuration, and current learning lifecycle.

Expand All @@ -30,6 +36,8 @@ Connect, disconnect, page access, and authorization phases write bounded securit

- Without a configured provider, Hub shows the configuration requirement and does not offer connection.
- A refused credential produces a denied change and records refusal state without saving a connection.
- A removed GitHub App installation, mismatched App or organization, or denied Copilot Requests permission produces a denied change for that exact provider configuration. Hub never falls back to a personal credential.
- GitHub throttling, network failures, and unreadable responses remain retryable failures and do not record terminal refusal state.
- An unavailable command or Copilot service produces a failed change and no connection.
- A stale, cancelled, expired, reused, or mismatched authorization changes nothing.
- When the connector loses their final effective administrator assignment, the same authority transaction disconnects Copilot, advances the connection generation, and audits the automatic change.
Expand Down
5 changes: 5 additions & 0 deletions hub/docs/deployment.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,11 @@ Publishing is an explicit operator step, not a side effect of CI. From the appro
| `ON_DEMAND_JOB_CONCURRENCY`, `SCHEDULED_JOB_CONCURRENCY` | Independent worker concurrency, as described in [Background jobs](background-jobs.md). |
| `HUB_APPLICATION_ORIGIN` | Exact public HTTP origin required with any authentication provider. Provider settings enable routes; any authentication setting also requires `DATABASE_URL`. A database-backed runtime with no provider configured disables retained provider authority and registers no authentication routes. |
| `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | GitHub App user-authorization credentials. Keep the secret in protected runtime configuration. |
| `GITHUB_APP_ID` | Hub GitHub App identity used for organization-billed Copilot installation credentials. |
| `GITHUB_APP_PRIVATE_KEY` | App JWT signing key required by the shipped runtime. The signer remains replaceable in code for future governed runtime composition. |
| `REPLICA_COPILOT_AUTHENTICATION` | `github-app-installation` for organization billing, or an explicit local mode. Hub never falls back between credential modes. |
| `REPLICA_COPILOT_GITHUB_ORGANIZATION` | Organization billed for Copilot requests. |
| `REPLICA_COPILOT_GITHUB_INSTALLATION_ID` | Numeric installation ID for the Hub GitHub App in that organization. |
| `GITHUB_PROVIDER_REVISION` | Positive configured adapter revision. Increment consecutively for configuration changes and before re-enabling a removed provider. |
| `ENTRA_OIDC_ISSUER`, `ENTRA_OIDC_CLIENT_ID` | Exact single-tenant Entra v2 issuer and application client ID. See [Microsoft Entra OIDC](entra-oidc.md). |
| `ENTRA_OIDC_PROVIDER_REVISION` | Positive Entra adapter revision. Increment consecutively for configuration changes and before re-enabling a removed provider. |
Expand Down
Loading
Loading