GitHub integration

How the planned GitHub connector is intended to work, what it should unlock, and which boundaries matter.

GitHub is the next major connector planned for nicoolAI.

The goal is not to bolt on generic code automation. The goal is to let nicoolAI work in GitHub with the same product standard it uses elsewhere: explicit connection, bounded access, grounded execution, and clear refusal when the boundary is wrong.

Getting started

To get started with the planned GitHub connector, open the GitHub connector setup. The auth foundation and dashboard flow exist, but the end-user GitHub workflows described on this page should still be treated as upcoming rather than fully live.

What the GitHub connector is for

The planned GitHub connector is meant to support work such as:

repository-aware assistance
issue and pull request workflows
content and metadata reads
bounded write actions where the user and installation permissions allow them

In plain terms: if the work belongs in GitHub, nicoolAI should be able to operate there without turning GitHub access into a vague all-powerful agent permission.

The intended user experience

The planned flow is:

The user connects GitHub in the dashboard.
The connection is stored as a named connector such as personal or work.
The user authorizes nicoolAI through a GitHub App flow.
GitHub installation state determines which repos and orgs are actually reachable.
nicoolAI acts only where the connection, installation, and permission model all line up.

That last step matters most. A saved connection alone should not imply broad GitHub access.

Why the plan uses a GitHub App

The committed plan uses a GitHub App model instead of a plain OAuth App or pasted personal access tokens.

That is the right product shape because it gives nicoolAI:

explicit user authorization
refreshable credentials
actions attributed to the user
narrower, more legible permissions
installation-based boundaries for org and private repo access

What nicoolAI should eventually be able to do

The planned connector is intended to unlock:

reading repository metadata and contents
creating or updating issues
creating or updating pull requests
bounded content operations where permission is explicit

What it should not become:

a silent background operator across every repo the user can access
a broad token sink that bypasses repository or org boundaries
a hidden permission layer the user cannot reason about

Named connections

GitHub is planned to follow the same named-connection pattern as Google Drive.

Examples:

personal
work
client-a

That matters because many users do not operate from a single GitHub identity.

Fail-closed behavior

The committed plan is explicit about denial conditions.

GitHub work should fail closed when:

no active GitHub connection exists
token refresh fails
no installation covers the target repo or org
the required permission is missing
the user no longer has access

That behavior is not just technical caution. It is part of how the product stays trustworthy.

What is already decided in the plan

The committed plan already sets the core shape:

native dashboard connect flow
PKCE in the web auth flow
refreshable user-scoped token handling
named connections
installation-aware access boundaries
a canonical token broker for future runtime and sandbox work

What is not live yet

This connector is still planned, not live for end users.

That means:

no GitHub actions should be described as generally available yet
repo, issue, PR, and sandbox workflows should still be treated as upcoming
the docs should describe the intended model, not pretend the feature is already shipping