F
Flowman docsWorkflow SDK
Back to app
Connectors

GitHub connector

The GitHub connector links a project to a GitHub App installation so a run can read live pull request status from GitHub and project members can manage pull requests in Flowman. Unlike the IMAP connector, it is not a polling worker in connector-runtime — it is an on-demand integration. When you select Refresh PR status from Run actionson a run, Flowman queries GitHub for the run's pull requests, updates their stored state, and marks the workflow done once every PR is merged or closed. The same installation also lets the automatic Cursor Cloud ready-for-review Sub-agent convert linked draft PRs to ready.

Pull requests in Flowman

Open Pull requests after Coding in the project sidebar. Every configured repository appears, including disabled coding repositories and polyrepo members. Configure a GitHub repository URL for each repository in Coding → Repositories and include those repositories in the project’s GitHub App installation. Members, admins and owners can browse and operate pull requests; customers cannot access this section. Repositories with open pull requests appear first, ordered by open count.

Repository pages offer paginated Open, Closed (including merged), and All lists. Open counts include drafts. Overview shows the description, reviews, comments, review threads, merge status and individual checks. Files changed offers a searchable tree of loaded paths, unified and split source diffs, and read-only review annotations. Use Load more for files, discussions, checks, threads and replies. Outdated or unmappable comments retain their original context separately. PR pages use the available page width. GitHub descriptions and comments support sanitized HTML, expandable details, images and readable timestamps; wide tables scroll horizontally so their columns stay legible.

Counts, lists and overview status refresh every 60 seconds while the page is visible. Open counts use a shared cache for up to 60 seconds, with batched GitHub requests across repositories; confirmed merges and closes invalidate those counts. Refresh and Refresh all sections load current data on demand, using that cache for counts. If another viewer is loading counts, Flowman keeps the previous counts or asks you to refresh shortly. No persistent PR mirror is created. Selected-file patches are limited to 512 KiB and GitHub returns at most 3,000 changed files. Binary, omitted, oversized and incomplete patches show an explanation and a GitHub fallback link. Search covers loaded paths only.

Merge confirms the PR, target branch and repository-enabled method (squash preferred). Flowman rechecks GitHub’s merge protections and sends the reviewed head commit; a changed head or target requires refreshing and reviewing again. Close requires confirmation and preserves the source branch. Open drafts can be marked ready for review. Successful actions appear in project activity and reconcile linked runs using the existing polyrepo, Jira completion and local base-sync rules. If GitHub succeeds but local synchronization fails, the confirmed result includes a warning; refresh or a signed webhook retries synchronization.

Version one does not create PRs, write reviews or comments, edit metadata, reopen PRs, delete branches, enable auto-merge or merge queues, browse entire repositories, or display full CI logs. Check details link to their provider. Access or section failures preserve other usable data. Rate limits pause requests until GitHub’s retry window.

Create the GitHub App

One GitHub App serves the whole Flowman instance. In GitHub, go to Settings → Developer settings → GitHub Apps → New GitHub App and configure:

After changing App permissions, each installation owner must accept the update in GitHub Settings → Applications → Installed GitHub Apps → Configure (or through GitHub’s permission-request email). Changing the App definition alone does not grant existing installations new permissions. Revisit Connectors → GitHub → Manage on GitHub to confirm repository access. Missing Checks or Commit statuses permissions show setup guidance without blocking the rest of the PR.

  • Repository permissions: Contents: Read and write, Pull requests: Read and write, Checks: Read-only, Commit statuses: Read-only, and Metadata: Read-only. Contents and pull-request write access are required for Codex Cloud to push its working branch and create or update the run's pull request. Pull-request write access is also required for Cursor Cloud's deterministic ready-for-review child.
  • Setup URL: <APP_URL>/api/connectors/github/setup, with "Redirect on update" enabled so reinstalls return to Flowman.
  • Subscribe to the Pull request webhook event pointed at <APP_URL>/api/webhooks/github/pull-request. When a Flowman-linked PR is merged or closed, Flowman records the terminal state and marks the run done automatically — the same outcome as selecting Refresh PR status. For local coding sessions started from Jira Intake, completion first queues the installed completion skill so it can verify the base branch, transition the linked Jira issue to Done, and then finish the Flowman run. Other local sessions queue a runtime base-branch sync so the workspace checks out and fast-forward pulls the PR target when the worktree is clean. The same subscription links pull requests that agent-managed repositories open through their own skills: on opened, reopened, ready-for-review and closed events, Flowman matches the PR's head branch to a worktree the runtime observed for a run.
  • Generate a private key (PEM), and note the App ID, client id/secret, and the app slug.

Environment variables

Set these on the Flowman web/Convex deployment (instance-wide):

  • GITHUB_APP_ID — the numeric App ID.
  • GITHUB_APP_PRIVATE_KEY — the PEM private key (literal \n escapes are accepted).
  • GITHUB_APP_SLUG — the app slug used to build the install URL.
  • GITHUB_APP_CLIENT_ID / GITHUB_APP_CLIENT_SECRET— the app's OAuth client credentials.
  • Reuse FLOWMAN_PR_COMPLETION_TOKEN on both the Next.js app and Convex deployment. For the pull request webhook, also set GITHUB_WEBHOOK_SECRET to the secret configured on the GitHub App webhook.

Connect a project

On /p/<slug>/connectors an admin presses Connect GitHub. Flowman redirects to GitHub's installation page; after you choose the repositories, GitHub returns to the setup URL and Flowman stores the installation id for the project (scoped per project, like other credentials). Each project keeps only the installation id — the App private key never leaves the server environment.

Refresh PR status and finalize

When Cursor Cloud finishes its initial implementation and Flowman has linked at least one PR, a Flowman-managed Sub-agent mints a short-lived installation token, reads every PR's live draft state, and uses GitHub's ready-for-review mutation for drafts. One child covers all polyrepo PRs. It is idempotent and independently retryable, so an already-ready PR succeeds without another mutation and a child failure does not change the completed implementation result.

When a run has an open pull request, Run actions includes Refresh PR status. With GitHub connected, selecting it mints a short-lived installation token, reads each pull request via the GitHub REST API, and maps the result to Flowman's open / closed / merged state. When all linked pull requests are merged or closed, the coding session and workflow run are marked done. Jira-linked local sessions first queue the installed completion skill and require its verified Jira Done result. Other local sessions also queue a runtime base-branch sync (checkout + ff-only pull of the PR target when the worktree is clean). If the GitHub App webhook is configured, the same finalize happens automatically when GitHub delivers a pull_request closed event. If GitHub is not connected, the button falls back to asking the coding agent to reconcile completion.