Integrations
An integration connects FlowWright to GitHub or GitLab so that pushing code starts a run, and so a run's result appears back on the commit.
Running in CI is about invoking flow run as a step inside someone else's CI
job. This page is about FlowWright's own app — its webhooks, its checkout tokens, its status
reporting. The two share every proper noun and overlap in nothing.
Two halves, two roles
An instance admin registers the app once, under the admin settings: a GitHub App (app id, slug, private key, webhook secret) or a GitLab OAuth application (application id, secret). The screen then shows the callback and webhook URLs to paste back into the provider.
Those URLs are derived from the server's external base URL. Until that is set they are blank, and nothing works — the provider has nowhere to call and the OAuth redirect is malformed. Set it to the origin the provider's servers can reach. The full screen is covered in the admin section.
A workspace admin then connects an installation, from Integrations inside their workspace. Connecting redirects to the provider, grants access, and returns.
Repositories
An installation carries the repositories it can see. Sync re-reads that list. Rescan additionally looks for pipeline files and onboards. Disconnect revokes what it can, deletes the stored credentials and removes the installation.
You can only link a repository the last sync actually saw, and the link is by the provider's immutable repository id — so renaming the repository upstream doesn't break it. A repository links to at most one project per workspace, and a project links to at most one repository, which is what keeps webhook routing unambiguous.
From the browser you can create a project directly from a repository. That is two steps — the project, then the link — and if the second fails you're left with an unlinked project to delete.
Auto-onboarding
An installation can discover work for itself. It creates one project per repository — not one per branch and not one per pull request. A repository qualifies when the pipeline file is present at some branch tip, or, with pull-request discovery on, at the head of some open PR. Forks are ignored, and both passes stop at fifty branches or PRs per repository.
A repository where the file has disappeared everywhere gets its project archived, not deleted; the history stays.
Auto-onboarding is on by default for a GitHub organisation install. A GitLab install connected from the workspace Integrations screen does not auto-onboard — GitLab reports the account as a user, and only an org account opts in automatically.
What turns a push into a run
A linked project carries a trigger policy with three independent sections — push branches, pull-request actions, tag patterns. Branches and tags are glob-matched; PR actions are an exact list. A section you leave empty means that kind of event never fires, and a link with no sections at all triggers nothing.
The policy is edited on the project's Triggers tab, on the repository-link panel.
Even an accepted event can still be skipped, and the two common reasons are worth knowing:
- The pipeline file isn't present at that commit. The check is per-event and fail-closed — a push to a branch that doesn't have the file yet is skipped, with the reason recorded.
- The project or its workspace is archived, or the installation is suspended or revoked.
Every skip is recorded against the delivery, so the reason is never a mystery — it's just not on the project's page.
Deliveries
Every verified webhook is stored before it is processed, and the Integrations screen lists them with their status: received, processed, skipped, or failed. Skipped ones carry the reason above; failed ones carry the error.
Retry applies to a failed delivery. Replay re-processes any delivery that still has its stored event, whatever its status — the recovery tool when something downstream was broken and has since been fixed. Neither can produce a duplicate run: the run is keyed by delivery id. Failed deliveries are also retried automatically, up to five attempts.
Signature verification happens before the payload is parsed, and a delivery that fails it is never recorded — so an unverified webhook leaves no trace here at all.
GitHub and GitLab are not equivalent
| GitHub | GitLab | |
|---|---|---|
| Auth | one app, instance-wide | OAuth, per installation |
| Run status | a check run with a summary and failing-test annotations | a commit status, description truncated to 140 characters |
| Auto-onboard on connect | organisation installs, automatically | never from the workspace screen |
| Webhook identity | carried in the event | resolved from the repository, which must already be synced |
That last row has a consequence: a GitLab event for a repository the installation hasn't synced yet is rejected and not recorded as a delivery.
GitLab deliveries are verified against a per-installation secret that FlowWright generates and stores itself. Nothing currently surfaces that value, so there is no way to paste it into GitLab's own webhook settings. GitHub's flow is complete; on GitLab, treat repository discovery, linking and status reporting as working and webhook-driven triggering as not yet configurable.
Checkout tokens
A provider-triggered run needs credentials to clone. The server mints a short-lived token per run; the app's private key or OAuth secret never reaches a worker. Workers running inside the server process get this automatically.
Without both, provider runs don't fail — the worker clones the branch tip with no token.
On a private repository that surfaces as a confusing clone failure. On a public one it
succeeds and builds the wrong commit, then reports a status against the commit that
triggered it. Set FW_SERVER_URL and enrol the worker.
Read next
- Projects — the project a repository links to
- Runs — what a triggered run looks like
- Credentials — the other kind of provider