mirror of https://github.com/different-ai/openwork synced 2026-04-25 17:15:34 +02:00

Files

Source Open 6053ac937e feat(plugin-system): GitHub connector, discovery, marketplaces, and access UX (#1525 )

* feat(plugin-system): add GitHub connector, discovery, marketplaces, and access UX

End-to-end GitHub App connector flow and UI:

- GitHub App connect: install start/callback/complete endpoints, connector account upsert from installation, selection state, and a dedicated Den Web setup page.
- Repo discovery: GitHub tree + manifest inspection, Claude-compatible classification (marketplace/plugin-manifest), marketplace plugin metadata/component path parsing, discovery API + snapshot.
- Apply pipeline: materialize plugins, connector mappings, config objects (with frontmatter-aware skill/agent parsing), memberships, and source bindings; create marketplaces with name/description from marketplace.json.
- Auto-import on push: persist flag on connector instance, webhook-driven re-apply for new discoveries.
- Cleanup: cascading disconnect on connector account removal and remove on connector instance.
- Integrations UI: cleaner connected-account card, GitHub avatar, hover trash + confirm dialog, inline "Add new repo" action, per-account repo picker, manifest badges, configured/unconfigured sorting.
- Discovery UI: cleaner loader, plugin cards with component chips, inline apply action, auto-import toggle default on.
- Manage UI: instance configuration endpoint, auto-import toggle, remove repo danger zone with cascade confirmation.
- Plugins & Marketplaces pages: dashboard nav entries, list + detail screens, per-plugin component counts, marketplace resolved endpoint with source + plugins, marketplace access section (org-wide/team/member grants).
- Bitbucket card marked "Coming soon".
- PRDs, GitHub setup instructions, and learnings docs added.

* chore(docs): move GitHub-instructions.md into prds/new-plugin-arch/github-connection

* fix(den-web): wrap github integration page in Suspense for useSearchParams

* refactor(den-web): redirect GitHub post-install flow into the clean account selection phase

After completing the GitHub App install, previously we rendered a separate
GithubRepositorySelectionPhase with different styling. Now we call the install
completion endpoint, then router.replace to ?connectorAccountId=... so the
existing GithubConnectedAccountSelectionPhase renders the repo list. Removes
the duplicate selection phase and its unused helpers/imports.

* fix(den-web): drop Requires-scopes body and show GitHub description in integrations card

Removes the empty-state Requires scopes: <code>… block from both provider
cards and restores the provider description on the GitHub card so the empty
state is consistent with Bitbucket. Drops the header's bottom border when no
body follows.

* fix(den-web): only show integration provider description in empty state

Once a provider has connections, hide the description in the header so the
card focuses on the connected accounts + repos list.

---------

Co-authored-by: src-opn <src-opn@users.noreply.github.com>

2026-04-22 17:27:59 -07:00

5.2 KiB

Raw Blame History

GitHub Connection UX Plan

Goal

Define the desired user experience for connecting GitHub to OpenWork in den-web (cloud), independent of the current implementation state.

This flow is for the den-api plugin connector system and GitHub App based connector onboarding.

Desired user flow

User is in OpenWork den-web (cloud).
User sees an Integrations entry point.
User opens Integrations.
User sees a GitHub integration card.
User clicks Connect on GitHub.
OpenWork sends the user to the GitHub App install/authorize flow.
User completes the normal GitHub steps on GitHub.
GitHub returns the user to OpenWork.
OpenWork recognizes the completed GitHub App installation for the current org/user context.
OpenWork shows the user the list of repositories available through that installation.
User selects one repository.
OpenWork creates a new GitHub connector instance for that selected repository.
OpenWork configures webhook-driven sync for that repository.
Future pushes to the connected repository trigger OpenWork sync behavior through the connector pipeline.

Product expectations

Integrations surface

den-web should expose a clear Integrations UI in cloud mode.
GitHub should appear as a first-class integration option.
The user should not need to manually paste GitHub installation ids or repository ids.

Connect action

Clicking Connect should start a GitHub App flow, not a legacy OAuth-only flow.
The flow should preserve enough OpenWork context to return the user to the correct org and screen after GitHub finishes.
The GitHub-side step should feel like a normal GitHub App installation flow.

Return to OpenWork

After GitHub redirects back, OpenWork should detect the installation that was just created or updated.
If installation state is incomplete or ambiguous, OpenWork should guide the user instead of silently failing.
The user should land back in the GitHub integration flow, not on a generic page with no next step.

Repository selection

OpenWork should list repositories available to the installation.
The user should be able to pick one repository as the first connected source.
Selecting a repository should create a connector instance for that repo in the current OpenWork org.
The UX may later support branch choice and mapping choice, but repository selection is the minimum required step.

Webhook + sync expectation

Once connected, OpenWork should be ready to receive GitHub App webhooks for the selected repository.
Pushes on the tracked branch should enter the connector sync pipeline.
The system should present this as a connected integration, not as a hidden backend-only setup.

User-facing behavior requirements

The user should not need to know what an installation id is.
The user should not need to call admin APIs manually.
The user should not need to configure webhooks manually in normal product usage.
The user should be able to understand whether GitHub is:
- not connected
- connected but no repository selected
- connected and repository syncing
- connected but needs attention

Desired backend behavior

To support the UX above, the backend flow should conceptually do the following:

Generate or expose the GitHub App install URL.
Preserve OpenWork return context across the redirect.
Handle the GitHub return/callback.
Resolve the GitHub App installation id associated with the user action.
Create or update the corresponding connector_account.
List repositories accessible through that installation.
On repo selection, create:
- a connector_instance
- a connector_target for the repo/branch
- any initial mappings needed for ingestion
Ensure webhook events can resolve that connector target.
Queue sync work when relevant webhook events arrive.

UX principles

Prefer a short, guided flow over a configuration-heavy admin experience.
Favor product language like Connect GitHub over backend nouns like connector account.
Hide raw GitHub/App identifiers from the normal UX unless needed for support/debugging.
Keep the first-run flow focused on success: install, return, pick repo, connected.
Advanced settings can exist later, but should not block first connection.

Success criteria

The experience is successful when:

A cloud user can start from den-web without using terminal commands.
The user can complete GitHub App installation from the app.
The user returns to OpenWork automatically.
OpenWork shows repositories from that installation.
The user selects a repo.
OpenWork creates a connector instance for that repo.
GitHub webhooks for that repo can be accepted and associated to the instance.
The connection state is visible in the product UI.

Non-goals for this document

Exact API shapes for every route.
Full ingestion/reconciliation design details.
Delivery/install runtime behavior for connected content.
Final UI layout or visual design.

Next planning step

Translate this desired UX into an implementation plan that maps:

den-web screens and states
den-api routes and callback behavior
GitHub App configuration requirements
connector-account / connector-instance creation behavior
webhook readiness and initial sync behavior

5.2 KiB Raw Blame History