Webhooks
Configure webhooks from your git provider to enable automation features.
Overview
Webhooks allow Forkline to receive real-time repository events such as:
- Issue and pull request comments
- Issue, pull request, and merge request lifecycle updates
- CI pipeline, check, and status failures
Info: Webhooks are required for bot mentions, CI auto-fix, merge conflict automation, and auto review.
App-managed events
Issues, PRs, comments, checks, and status arrive automatically.
Manual project webhook
Configure issue, comment, MR, and pipeline events.
Manual repo webhook
Configure issue, PR, comment, action, and status events.
Event normalization
Forkline verifies the secret, classifies the event, and selects the matching automation workflow.
Bot Mentions
Thread-triggered tasks from issues and pull requests.
Auto Review
Reviews started from new PR or MR activity.
CI + Conflict Fixes
Failures and mergeability changes become follow-up work.
How It Works
When you activate a repository in Forkline, GitHub App connectors create the needed webhooks automatically. GitLab and Forgejo connectors expose a webhook URL that you configure manually on the provider side.
Note: On GitLab and Forgejo, a webhook only acts on repositories that are registered under the connector it belongs to. Each owner adds their own webhook for their own repositories. If two people register the same repository under their own connectors, each person’s webhook creates tasks only for that person. A collaborator who has not set up a webhook of their own does not get tasks through someone else’s webhook. GitHub is different: GitHub webhooks are created automatically by the Forkline GitHub App, so no per-owner setup is needed.
Supported Events
Forkline uses webhooks for these flows:
| Feature | Webhook usage |
|---|---|
| Bot mentions | Comments and new issue or pull request bodies |
| Auto review and trigger policies | Issue, pull request, and merge request updates |
| Merge conflict automation | Pull request or merge request updates |
| CI auto-fix | Pipeline, check, or status failures |
The exact event names depend on your git provider.
GitHub
GitHub App connectors automatically configure both webhooks and permissions. When you accept the installation, Forkline receives the events it needs without any extra manual steps.
The Forkline GitHub App requests:
- Contents (write): Clone repositories, push commits, manage branches
- Issues (write): Read issues, create comments, manage issue metadata
- Pull requests (write): Create PRs, read PR details, comment, approve, and reject
These permissions are fixed because Forkline needs to push code and create PRs on your behalf.
GitLab
For GitLab connectors, configure the project webhook manually:
- Go to your project Settings -> Webhooks
- Enter your Forkline webhook URL
- Set a secret token
- Select the trigger events
- Save
Enable these GitLab trigger events:
| GitLab trigger | Required | Used for |
|---|---|---|
| Issues events | Yes | Bot mentions in issue bodies and issue-based automation |
| Comments events | Yes | Bot mentions in issue and merge request comments |
| Merge request events | Yes | Auto review, merge conflict automation, merge request body triggers, and merge request policy updates |
| Pipeline events | Optional | CI auto-fix for failed GitLab pipelines |
Note: Forkline currently handles GitLab’s
Issue Hook,Note Hook,Merge Request Hook, and, for CI auto-fix,Pipeline Hook.
Forgejo
For Forgejo, Gitea, and Codeberg connectors:
- Go to your repository Settings -> Webhooks
- Click Add webhook -> Forgejo webhook or Gitea webhook
- Enter your Forkline webhook URL
- Set content type to
application/json - Configure a secret
- Select trigger events
- Save
Enable these Forgejo trigger events:
| Forgejo trigger | Required | Used for |
|---|---|---|
| Issues | Yes | Bot mentions in issue bodies and issue-based automation |
| Issue comments | Yes | Bot mentions in issue comments |
| Pull requests | Yes | Auto review, merge conflict automation, pull request body triggers, and pull request policy updates |
| Pull request comments | Yes | Bot mentions in pull request comments |
| Push | Optional | Pausing CI auto-fix when you push commits after Forkline has pushed a fix |
| Check runs | Optional | CI auto-fix for Forgejo Actions checks |
| Action run events | Optional | CI auto-fix on instances that expose action run webhook events |
| Status | Optional | CI auto-fix when your repository uses external commit status checks |
Note: Use the same webhook secret in both your Forgejo settings and your Forkline connector configuration.
Webhook Security
Always configure webhook secrets:
| Provider | Header | Verification |
|---|---|---|
| GitHub | X-Hub-Signature-256 |
HMAC-SHA256 |
| GitLab | X-Gitlab-Token |
Token comparison |
| Forgejo | X-Gitea-Signature |
HMAC-SHA256 |
Warning: Without secrets, webhook requests can be spoofed.
Webhook Limits
To keep one noisy or misconfigured sender from affecting everyone else, Forkline rate-limits webhook deliveries. The limits are generous, so normal traffic (including a burst such as a bot opening dozens of pull requests at once) is not affected.
| Limit | Applies to | Default (per Forkline server; the effective limit is higher) |
|---|---|---|
| Per connector | One GitLab or Forgejo connector, GitHub installation, or custom webhook | 600 requests per minute, burst of 200 |
| Per source IP | Custom webhooks | 1200 requests per minute, burst of 400 |
Deliveries from GitHub, GitLab and Forgejo are not limited per IP, because GitHub.com, GitLab.com and Codeberg send webhooks for every account from shared addresses.
A delivery over a limit is answered with HTTP 429 Too Many Requests and a Retry-After header (in seconds). It is not processed. Whether the sender retries depends on the forge:
- GitHub does not redeliver automatically. Forkline’s GitHub App deliveries can only be redelivered by Forkline, within 3 days. Contact support if events were rate-limited.
- GitLab does not redeliver automatically. A hook that fails 4 times in a row is temporarily disabled (from 1 minute up to 24 hours) and skips events while disabled; after 40 consecutive failures it is disabled until you re-enable it (send a test request from the hook’s settings). On GitLab 17.10 and earlier, 4xx responses such as
429can disable the hook permanently after 4 failures. - Forgejo shows the failed delivery in the hook’s history, and you can redeliver it from there.
If you see 429 responses in your forge’s delivery log, reduce how often the hook fires (for example by narrowing the events it sends). Self-hosted Forkline operators can tune the limits with the controlPlane.webhookIngress Helm values.