[sergiocorral-conductorone]

INTENT

• Replace the "custom domain" note at the top of docs/connector.mdx with when-to-use guidance: github.com orgs, one org per GitHub App or several orgs with one PAT, fine-grained PAT support.
• Add org_role (sync + provision) to the Capabilities table; no enterprise roles, licenses, or last-activity.
• Document account provisioning behavior for EMU orgs and point to the IdP's GitHub SCIM integration.

What changed

docs/connector.mdx only: rewritten top note, new "Org roles" capability row, new EMU note under the provisioning paragraph.

Verified in code

• org_role sync + provision: baton_capabilities.json (org_role entry), pkg/connector/org_role.go (Grants, Grant, Revoke)
• Account provisioning sends an org invitation: pkg/connector/invitation.go (CreateAccount -> CreateOrgInvitation)
• EMU error ("accounts are provisioned by the IdP, not via org invitations"): pkg/connector/invitation.go (isEMUOrgError)
• PAT (token), GitHub App (app-id, org), multi-org (orgs): config_schema.json
• Fine-grained PAT: already documented in the connector page as an auth option

Open items

• PENDING, NOT COMPLETE: the shared "Choose a GitHub connector" guide (CXH-3497) has no real URL yet, so the INTENT item to link it in the top note is not done. No link or placeholder is in the mdx; add the link once the guide is published.
• Decision (review thread on the Capabilities table): enterprise roles are intentionally omitted. CXH-3498 limits this page to customer-facing GitHub v2 capabilities. A conditional enterprise_role implementation exists in code (requires the enterprises config) and is acknowledged, but it is not documented here.
• Not asserted in the docs: that fine-grained PAT support is exclusive to this connector (not verifiable in this repo).

Fixes CXH-3498

🤖 Generated with AI

[linear-code]

CXH-3498

[github-actions]

Superseded — see the current review report for commit 568c553c7b82

Connector PR Review: [CXH-3498] - Docs: baton-github — add "when to use" guidance and document missing capabilities

Blocking Issues: 0 | Suggestions: 1 | Threads Resolved: 0
Criteria: Criteria status: loaded .claude/skills/ci-review.md from trusted base 2c5bd7f375ec.
Review mode: full
View review run

Review Summary

This PR changes only docs/connector.mdx. It rewrites the top Tip with "when to use" guidance, adds an "Org roles" row (sync + provision) to the Capabilities table, and adds a Note on Enterprise Managed Users (EMU) under the account-provisioning paragraph. I scanned the full PR diff for security and correctness issues. No code, config, or dependency files changed.

Each documentation claim was checked against the code:

• Org roles: org_role is listed with CAPABILITY_SYNC,CAPABILITY_PROVISION in baton_capabilities.json.
• EMU error: isEMUOrgError in pkg/connector/invitation.go:290-291,495 produces the "provisioned by the IdP" error.
• Auth and orgs: config_schema.json has the single org field for a GitHub App and the multi-value orgs field for a personal access token.
• Fine-grained tokens: they are already documented as Option 2 in the same file.

The trusted repo-local criteria were applied. The Documentation Staleness checks (D1–D4) and the breaking-change gate (BP3) are the relevant ones, and they produced the one suggestion below. The code-level sections (log levels, error wrapping, spans, JSON types, provisioning, sync data loss) do not apply because no Go code changed.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• New: docs/connector.mdx:23: the Capabilities table still leaves out enterprise roles. The connector registers an enterprise_role resource type with a provisioning builder (pkg/connector/connector.go:92,160), and the enterprises config field describes syncing and provisioning it. The PR body says "no enterprise roles" without explaining why. Either add a row (noting it needs the enterprises config) or explain why it is left out. Confidence: medium.

Prompt for AI agents

Verify each finding against the current code and only fix it if needed.

## Suggestions

In `docs/connector.mdx`:
- Around line 18-26 (Capabilities table): The connector has an `enterprise_role` resource type (pkg/connector/connector.go:92) with sync and provisioning (EnterpriseRoleProvisioningBuilder), enabled through the `enterprises` config field. Add an "Enterprise roles" row with sync and provision checkmarks, plus a short note that it needs the `enterprises` config and enterprise admin rights (a GitHub App only syncs/provisions the built-in Owner role). If leaving it out is deliberate, say why in the PR description.

[github-actions]

Connector PR Review: [CXH-3498] - Docs: baton-github — add "when to use" guidance and document missing capabilities

Blocking Issues: 0 | Suggestions: 1 | Threads Resolved: 0
Criteria: Criteria status: loaded .claude/skills/ci-review.md from trusted base 2c5bd7f375ec.
Review mode: full
View review run

Review Summary

This PR changes only docs/connector.mdx. It rewrites the top Tip with "when to use" guidance, adds an "Org roles" row (sync + provision) to the Capabilities table, and adds a Note on Enterprise Managed Users (EMU) under the account-provisioning paragraph. I scanned the full PR diff for security and correctness issues. No code, config, or dependency files changed.

Each documentation claim was checked against the code:

• Org roles: org_role is listed with CAPABILITY_SYNC,CAPABILITY_PROVISION in baton_capabilities.json.
• EMU error: isEMUOrgError in pkg/connector/invitation.go:290-291,495 produces the "provisioned by the IdP" error.
• Auth and orgs: config_schema.json has the single org field for a GitHub App and the multi-value orgs field for a personal access token.
• Fine-grained tokens: they are already documented as Option 2 in the same file.

The trusted repo-local criteria were applied. The Documentation Staleness checks (D1–D4) and the breaking-change gate (BP3) are the relevant ones, and they produced the one suggestion below. The code-level sections (log levels, error wrapping, spans, JSON types, provisioning, sync data loss) do not apply because no Go code changed.

Security Issues

None found.

Correctness Issues

None found.

Suggestions

• New: docs/connector.mdx:23: the Capabilities table still leaves out enterprise roles. The connector registers an enterprise_role resource type with a provisioning builder (pkg/connector/connector.go:92,160), and the enterprises config field describes syncing and provisioning it. The PR body says "no enterprise roles" without explaining why. Either add a row (noting it needs the enterprises config) or explain why it is left out. Confidence: medium.

Prompt for AI agents

Verify each finding against the current code and only fix it if needed.

## Suggestions

In `docs/connector.mdx`:
- Around line 18-26 (Capabilities table): The connector has an `enterprise_role` resource type (pkg/connector/connector.go:92) with sync and provisioning (EnterpriseRoleProvisioningBuilder), enabled through the `enterprises` config field. Add an "Enterprise roles" row with sync and provision checkmarks, plus a short note that it needs the `enterprises` config and enterprise admin rights (a GitHub App only syncs/provisions the built-in Owner role). If leaving it out is deliberate, say why in the PR description.

---

Reviewed commit: 568c553c7b82

[github-actions]

No blocking issues found — see the full review report

[luisina-santos]

Holding this until the shared "Choose a GitHub connector" guide from CXH-3497 exists. That guide isn't written yet, and the parent issue requires all three connector pages to link it.

Once the guide is published, add the link to the note at the top of each page and merge these three PRs together:

• #196
• ConductorOne/baton-github-enterprise#33
• ConductorOne/baton-axiomatic-github-enterprise-cloud#16

[luisina-santos]

Link the shared "Choose a GitHub connector" guide from CXH-3497 here. The guide doesn't exist yet, so this PR should wait for it (see the review summary).

Nit: the last sentence still frames the choice by domain ("if you use a custom domain…"). It's accurate for this connector, since the UI has no instance URL field, but GHEC customers on github.com may also want GitHub Enterprise (enterprise roles, licenses, last activity) or GitHub Enterprise Cloud. The guide link should cover that.