Managed GitHub App connection
The managed GitHub App connects a workspace to GitHub for repository-backed Productivity data. GitHub consent, repository collection, and developer identity mapping are separate steps.
The managed connection is being introduced through a staged rollout and is not yet enabled for general use. This page describes its connection and readiness contract. Your workspace administrator can confirm availability. Until the managed flow is enabled for your workspace, use the existing GitHub App or personal access token setup.
Optional GitHub connection
GitHub supplies repository and pull request data for Productivity. Connecting it does not configure an AI model provider or prove that developer identities are mapped correctly.
Managed onboarding requires at least one enabled AI provider with valid configuration and required credentials. Onboarding checks configuration; use the provider connection test to verify access to the provider. GitHub connection is optional: you can skip it, finish the required AI setup, and connect GitHub later. Skipping GitHub does not disable governance for your connected AI tools. GitHub-backed Productivity results remain unavailable or incomplete until you connect GitHub, onboard repositories, and collect data. See Add a provider and Productivity analytics.
When the managed connection is enabled, administrators can connect GitHub even if Productivity is not yet enabled for the workspace. Connection controls remain available; a deployment administrator must enable Productivity before repository management and collection results are available.
Consent and account authority
A workspace administrator starts the connection from the workspace and returns to that same workspace after GitHub consent. Use the intended GitHub account and keep the initiating workspace session open. A GitHub redirect or an installation ID alone does not connect an account.
For an organization installation, the GitHub user completing authorization must be an active organization owner. For a supported personal-account installation, that user must own the account. Being a repository contributor or an ordinary organization member does not grant authority to connect the organization's installation.
GitHub organization policy may require owner approval. An approval request is not a completed connection: collection remains unavailable until approval and connection verification finish. If you cancel, the request expires, or your workspace session changes, start a fresh connection from the workspace. Installing the App directly from GitHub does not automatically choose or connect an AIControls workspace. An already installed App still requires workspace authorization and verification; an installation already bound to another workspace cannot be silently reassigned.
The managed flow uses Nirmata's GitHub App. You do not create an App or paste its private signing key or global webhook secret into your workspace. Existing personal access token and customer-managed App configurations remain supported during migration. Changing authentication is a separate, deliberate operation; installing the managed App does not automatically replace an existing integration.
Read-only access and repository scope
The managed App requests read-only access to repository metadata, contents, pull requests, and checks. Organization membership read access supports verification that the authorizing user is an organization owner. The integration does not request repository write access.
GitHub's installation settings define the repositories the App may access. You can grant selected repositories instead of all repositories. AIControls repository onboarding decisions then determine which accessible repositories it collects. Installing the App, selecting repositories in GitHub, or receiving a webhook does not by itself onboard every repository.
Review pending repositories and explicit skips in Manage Productivity Repositories. Expanding GitHub access does not cancel an explicit skip or change your chosen reporting scope. A repository removed from the installation stops being eligible for new collection, even if older data remains visible under your workspace's retention policy.
Connection and data readiness
Treat these as separate checks:
| Check | What it establishes | What may remain incomplete |
|---|---|---|
| GitHub approval and authorization | You approved access using the intended account | Workspace verification and repository onboarding |
| Local workspace setup | The verified broker connection has been committed to the workspace repository configuration | Existing credential migration, repository selection and collection coverage |
| Verified workspace connection | The workspace has a verified installation binding | Current collection eligibility and repository selection |
| Current installation access | The installation is available with the required read-only permissions | Access to an individual repository and its onboarding decision |
| Repository collection | Eligible onboarded repositories are being synchronized | Initial history, freshness, or coverage for other repositories |
| Developer identity mapping | Repository authors can be associated with workspace developers where supported | Unmapped authors and evidence needed for attribution |
If GitHub consent finishes while workspace setup is incomplete, the connection is not ready for local collection. An administrator can retry workspace setup after the underlying configuration or migration issue is corrected. Retrying preserves the existing repository namespace and historical data.
A connected installation with no onboarded repositories has no collected repository coverage. Initial synchronization can take time. Partial or missing data must not be read as proof of no developer activity or no AI contribution. Review repository coverage, collection health, and identity mappings before comparing Productivity results.
Suspension, disconnect, and reconnect
Suspension, uninstall, permission changes, and repository-access changes can pause new collection. A resume notification alone does not establish that access is safe to use again: AIControls must verify current GitHub state and the affected repository's eligibility. Ask an organization owner to correct GitHub approval, suspension, or permissions, then retry the connection or synchronization offered by your workspace.
Disconnecting stops new token issuance and collection through that workspace connection. It does not uninstall the App from GitHub or request deletion of historical Productivity data. Retained history follows the workspace's retention policy. A GitHub token issued before disconnect can remain valid until its expiry; disconnect is not an immediate revocation of that upstream token.
Reconnecting requires fresh authorization and verification. It must not replay old deliveries into the new connection, undo explicit repository skips, or automatically widen your reporting scope. Review repository access and collection health again after reconnecting. If you need to move an installation between workspaces or change environments, ask your workspace administrator to coordinate the transition rather than reusing another workspace's connection details.
AIControls staging and production use separate App connections. Approving access for one does not authorize the other. Check the workspace and App identity on the consent screen before granting access.