Merge: align GitHub App org-admin handoff artifacts (#1142) (#1144)

* Initial plan

* docs(extension): align issue 1073 app handoff checklist and secrets

Agent-Logs-Url: https://github.com/IBuySpy-Shared/basecoat/sessions/89ab8e91-2be6-43f8-8776-f5c4d03ccbd4

* docs(extension): clarify requiredMetadata handoff intent

Agent-Logs-Url: https://github.com/IBuySpy-Shared/basecoat/sessions/89ab8e91-2be6-43f8-8776-f5c4d03ccbd4

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 3 people

docs/operations/COPILOT_EXTENSION_GITHUB_APP_REGISTRATION.md

@@ -24,14 +24,13 @@ Use these baseline settings when creating the App:
 
 ### Repository Permissions
 
-- Contents: **Read-only**
-- Pull requests: **Read and write**
-- Actions: **Read and write**
-- Metadata: **Read-only** (implicit)
+Grant these permissions exactly:
 
-### Organization Permissions
+- `contents`: **read**
+- `pull_requests`: **write**
+- `actions`: **write**
 
-- Members: **Read-only** (recommended for org-scoped eligibility checks)
+`metadata:read` remains implicit and does not require a separate grant.
 
 ### Subscribe to Events
 
@@ -52,7 +51,7 @@ Use these baseline settings when creating the App:
 
 ## Validation Steps After Admin Work
 
-1. Confirm App is installed on `IBuySpy-Shared`.
+1. Confirm App is installed on `IBuySpy-Shared` and installation scope is correct.
 2. Confirm extension endpoint responds at health route.
 3. Confirm OAuth callback succeeds for org member.
 4. Confirm `@basecoat` appears in Copilot Chat and routes a test prompt.

docs/templates/copilot-extension/github-app-registration.template.json

@@ -12,9 +12,7 @@
     "actions": "write",
     "metadata": "read"
   },
-  "organizationPermissions": {
-    "members": "read"
-  },
+  "organizationPermissions": {},
   "events": [
     "pull_request",
     "pull_request_review",
@@ -29,9 +27,16 @@
     "BASECOAT_EXTENSION_WEBHOOK_SECRET",
     "BASECOAT_EXTENSION_PRIVATE_KEY_PEM"
   ],
+  "requiredMetadata": [
+    "app_id",
+    "client_id",
+    "installation_id"
+  ],
   "notes": [
     "Do not commit generated credentials.",
     "Store credentials in org/repo secrets manager.",
-    "Installation must target IBuySpy-Shared organization."
+    "requiredMetadata lists non-secret values to share in issue #1073 closure evidence.",
+    "Installation must target IBuySpy-Shared organization.",
+    "Share App ID, Client ID, and Installation ID with maintainers for issue #1073 closure."
   ]
 }

mcp/basecoat-extension/README.md

@@ -33,11 +33,11 @@ The Extension backend reads configuration from environment variables. All OAuth-
 
 | Variable | Required | Description |
 |---|---|---|
-| `BASECOAT_EXTENSION_GITHUB_APP_ID` | Yes | GitHub App ID (from app registration) |
-| `BASECOAT_EXTENSION_GITHUB_CLIENT_ID` | Yes | GitHub OAuth client ID |
-| `BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET` | Yes | GitHub OAuth client secret (vault-managed) |
+| `BASECOAT_EXTENSION_APP_ID` | Yes | GitHub App ID (from app registration) |
+| `BASECOAT_EXTENSION_CLIENT_ID` | Yes | GitHub OAuth client ID |
+| `BASECOAT_EXTENSION_CLIENT_SECRET` | Yes | GitHub OAuth client secret (vault-managed) |
 | `BASECOAT_EXTENSION_WEBHOOK_SECRET` | Yes | Webhook signature secret (vault-managed) |
-| `BASECOAT_EXTENSION_GITHUB_PRIVATE_KEY` | Yes | GitHub App private key in PEM format (vault-managed) |
+| `BASECOAT_EXTENSION_PRIVATE_KEY_PEM` | Yes | GitHub App private key in PEM format (vault-managed) |
 
 ### OAuth & Session Tuning
 
@@ -69,11 +69,11 @@ The Extension backend reads configuration from environment variables. All OAuth-
 
 ```bash
 # Required: GitHub App credentials
-BASECOAT_EXTENSION_GITHUB_APP_ID=123456
-BASECOAT_EXTENSION_GITHUB_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8
-BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+BASECOAT_EXTENSION_APP_ID=123456
+BASECOAT_EXTENSION_CLIENT_ID=Iv1.a1b2c3d4e5f6g7h8
+BASECOAT_EXTENSION_CLIENT_SECRET=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 BASECOAT_EXTENSION_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
-BASECOAT_EXTENSION_GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"
+BASECOAT_EXTENSION_PRIVATE_KEY_PEM="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"
 
 # Optional: OAuth & session tuning
 BASECOAT_EXTENSION_OAUTH_STATE_TTL_MS=600000

mcp/basecoat-extension/scripts/bootstrap-credentials.ps1

@@ -23,18 +23,18 @@ Prerequisites:
 - Azure CLI (az) authenticated with Key Vault permissions (optional, for production)
 
 .PARAMETER AppId
-GitHub App ID. If not provided, reads from $env:BASECOAT_EXTENSION_GITHUB_APP_ID
+GitHub App ID. If not provided, reads from $env:BASECOAT_EXTENSION_APP_ID
 If not provided, script will prompt you to create app manually via GitHub UI.
 
 .PARAMETER OrgName
 GitHub organization for app creation guidance. Default: IBuySpy-Shared (extracted from $Repo)
 Only used if credentials are missing (to show correct creation link).
 
 .PARAMETER ClientId
-GitHub OAuth Client ID. If not provided, reads from $env:BASECOAT_EXTENSION_GITHUB_CLIENT_ID
+GitHub OAuth Client ID. If not provided, reads from $env:BASECOAT_EXTENSION_CLIENT_ID
 
 .PARAMETER ClientSecret
-GitHub OAuth Client Secret. If not provided, reads from $env:BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET
+GitHub OAuth Client Secret. If not provided, reads from $env:BASECOAT_EXTENSION_CLIENT_SECRET
 
 .PARAMETER WebhookSecret
 GitHub webhook signature secret. If not provided, reads from $env:BASECOAT_EXTENSION_WEBHOOK_SECRET
@@ -58,9 +58,9 @@ PS> .\bootstrap-credentials.ps1
 
 .EXAMPLE
 # Minimal interaction: set creds, no app creation
-PS> $env:BASECOAT_EXTENSION_GITHUB_APP_ID = "123456"
-PS> $env:BASECOAT_EXTENSION_GITHUB_CLIENT_ID = "Iv1.a1b2c3d4..."
-PS> $env:BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET = "ghp_xxxxxxxx"
+PS> $env:BASECOAT_EXTENSION_APP_ID = "123456"
+PS> $env:BASECOAT_EXTENSION_CLIENT_ID = "Iv1.a1b2c3d4..."
+PS> $env:BASECOAT_EXTENSION_CLIENT_SECRET = "ghp_xxxxxxxx"
 PS> $env:BASECOAT_EXTENSION_WEBHOOK_SECRET = "whsec_xxxxxxxx"
 PS> $env:BASECOAT_EXTENSION_PRIVATE_KEY_PATH = "./private-key.pem"
 PS> .\bootstrap-credentials.ps1
@@ -82,13 +82,13 @@ Updated: Bootstrap with auto-create GitHub App capability
 
 param(
     [Parameter(Mandatory = $false)]
-    [string]$AppId = $env:BASECOAT_EXTENSION_GITHUB_APP_ID,
+    [string]$AppId = $env:BASECOAT_EXTENSION_APP_ID ?? $env:BASECOAT_EXTENSION_GITHUB_APP_ID,
 
     [Parameter(Mandatory = $false)]
-    [string]$ClientId = $env:BASECOAT_EXTENSION_GITHUB_CLIENT_ID,
+    [string]$ClientId = $env:BASECOAT_EXTENSION_CLIENT_ID ?? $env:BASECOAT_EXTENSION_GITHUB_CLIENT_ID,
 
     [Parameter(Mandatory = $false)]
-    [string]$ClientSecret = $env:BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET,
+    [string]$ClientSecret = $env:BASECOAT_EXTENSION_CLIENT_SECRET ?? $env:BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET,
 
     [Parameter(Mandatory = $false)]
     [string]$WebhookSecret = $env:BASECOAT_EXTENSION_WEBHOOK_SECRET,
@@ -163,9 +163,9 @@ function Show-AppCreationGuide {
     Write-Host "  4. Download private key (PEM format)" -ForegroundColor Cyan
     Write-Host ""
     Write-Host "  5. Run bootstrap with credentials:" -ForegroundColor Cyan
-    Write-Host "     `$env:BASECOAT_EXTENSION_GITHUB_APP_ID = 'YOUR_APP_ID'" -ForegroundColor Green
-    Write-Host "     `$env:BASECOAT_EXTENSION_GITHUB_CLIENT_ID = 'YOUR_CLIENT_ID'" -ForegroundColor Green
-    Write-Host "     `$env:BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'" -ForegroundColor Green
+    Write-Host "     `$env:BASECOAT_EXTENSION_APP_ID = 'YOUR_APP_ID'" -ForegroundColor Green
+    Write-Host "     `$env:BASECOAT_EXTENSION_CLIENT_ID = 'YOUR_CLIENT_ID'" -ForegroundColor Green
+    Write-Host "     `$env:BASECOAT_EXTENSION_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'" -ForegroundColor Green
     Write-Host "     `$env:BASECOAT_EXTENSION_WEBHOOK_SECRET = 'YOUR_WEBHOOK_SECRET'" -ForegroundColor Green
     Write-Host "     `$env:BASECOAT_EXTENSION_PRIVATE_KEY_PATH = './private-key.pem'" -ForegroundColor Green
     Write-Host "     .\bootstrap-credentials.ps1" -ForegroundColor Green
@@ -185,19 +185,19 @@ if (-not $AppId -and (-not $ClientId -or -not $ClientSecret -or -not $WebhookSec
 
 # Validate that credentials are provided (either via params or env vars)
 $missingCredentials = @()
-if (-not $AppId) { $missingCredentials += "AppId (set env var BASECOAT_EXTENSION_GITHUB_APP_ID or pass -AppId)" }
-if (-not $ClientId) { $missingCredentials += "ClientId (set env var BASECOAT_EXTENSION_GITHUB_CLIENT_ID or pass -ClientId)" }
-if (-not $ClientSecret) { $missingCredentials += "ClientSecret (set env var BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET or pass -ClientSecret)" }
+if (-not $AppId) { $missingCredentials += "AppId (set env var BASECOAT_EXTENSION_APP_ID or pass -AppId)" }
+if (-not $ClientId) { $missingCredentials += "ClientId (set env var BASECOAT_EXTENSION_CLIENT_ID or pass -ClientId)" }
+if (-not $ClientSecret) { $missingCredentials += "ClientSecret (set env var BASECOAT_EXTENSION_CLIENT_SECRET or pass -ClientSecret)" }
 if (-not $WebhookSecret) { $missingCredentials += "WebhookSecret (set env var BASECOAT_EXTENSION_WEBHOOK_SECRET or pass -WebhookSecret)" }
 
 if ($missingCredentials.Count -gt 0) {
     Write-Error-Custom "Missing required credentials:"
     $missingCredentials | ForEach-Object { Write-Host "  - $_" -ForegroundColor Red }
     Write-Host ""
     Write-Info "To bootstrap with smart defaults, set these environment variables:"
-    Write-Host "  `$env:BASECOAT_EXTENSION_GITHUB_APP_ID = '...'"
-    Write-Host "  `$env:BASECOAT_EXTENSION_GITHUB_CLIENT_ID = '...'"
-    Write-Host "  `$env:BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET = '...'"
+    Write-Host "  `$env:BASECOAT_EXTENSION_APP_ID = '...'"
+    Write-Host "  `$env:BASECOAT_EXTENSION_CLIENT_ID = '...'"
+    Write-Host "  `$env:BASECOAT_EXTENSION_CLIENT_SECRET = '...'"
     Write-Host "  `$env:BASECOAT_EXTENSION_WEBHOOK_SECRET = '...'"
     Write-Host "  `$env:BASECOAT_EXTENSION_PRIVATE_KEY_PATH = './private-key.pem' (optional; defaults to ./private-key.pem)"
     Write-Host ""
@@ -215,20 +215,20 @@ $PrivateKey = Get-Content $PrivateKeyPath -Raw
 # Store in GitHub repository secrets (for CI/CD workflow)
 Write-Info "Storing credentials in GitHub repository secrets..."
 try {
-    gh secret set BASECOAT_EXTENSION_GITHUB_APP_ID --body "$AppId" --repo "$Repo"
-    Write-Status "Secret set: BASECOAT_EXTENSION_GITHUB_APP_ID"
+    gh secret set BASECOAT_EXTENSION_APP_ID --body "$AppId" --repo "$Repo"
+    Write-Status "Secret set: BASECOAT_EXTENSION_APP_ID"
 
-    gh secret set BASECOAT_EXTENSION_GITHUB_CLIENT_ID --body "$ClientId" --repo "$Repo"
-    Write-Status "Secret set: BASECOAT_EXTENSION_GITHUB_CLIENT_ID"
+    gh secret set BASECOAT_EXTENSION_CLIENT_ID --body "$ClientId" --repo "$Repo"
+    Write-Status "Secret set: BASECOAT_EXTENSION_CLIENT_ID"
 
-    gh secret set BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET --body "$ClientSecret" --repo "$Repo"
-    Write-Status "Secret set: BASECOAT_EXTENSION_GITHUB_CLIENT_SECRET"
+    gh secret set BASECOAT_EXTENSION_CLIENT_SECRET --body "$ClientSecret" --repo "$Repo"
+    Write-Status "Secret set: BASECOAT_EXTENSION_CLIENT_SECRET"
 
     gh secret set BASECOAT_EXTENSION_WEBHOOK_SECRET --body "$WebhookSecret" --repo "$Repo"
     Write-Status "Secret set: BASECOAT_EXTENSION_WEBHOOK_SECRET"
 
-    gh secret set BASECOAT_EXTENSION_GITHUB_PRIVATE_KEY --body "$PrivateKey" --repo "$Repo"
-    Write-Status "Secret set: BASECOAT_EXTENSION_GITHUB_PRIVATE_KEY"
+    gh secret set BASECOAT_EXTENSION_PRIVATE_KEY_PEM --body "$PrivateKey" --repo "$Repo"
+    Write-Status "Secret set: BASECOAT_EXTENSION_PRIVATE_KEY_PEM"
 } catch {
     Write-Error-Custom "Failed to set GitHub secrets: $_"
     exit 1