---
title: "Connect Git Provider"
description: "Connect GitHub, GitLab, or Forgejo to enable repository access and webhook automation."
section: "get-started"
url: "https://forkline.dev/docs/getting-started/connectors"
markdown: "https://forkline.dev/docs/getting-started/connectors.md"
source: "src/content/docs/getting-started/connectors.mdx"
---

# Git Providers

Git Providers give Forkline authenticated access to your repositories. Forkline supports GitHub, GitLab, and Forgejo, including self-hosted instances.

## Overview

When you connect a git provider, Forkline can:

- Clone repositories into runners with the right authentication
- Push changes back to branches and create pull requests
- Receive webhooks for automation triggers
- Call provider APIs for repository operations

> **Info**: Each git provider connection is user-specific. Your git providers only access repositories you can already view.

_Interactive figure (ConnectorComparisonBoard) — see the HTML version of this page._

![Git Providers page with GitHub connected](https://forkline.dev/docs/screenshots/connectors/connectors-page-full.webp)

## GitHub

The GitHub integration is the lowest-friction option because the GitHub App handles repository installation and webhook setup for you.

1. Go to **Git Providers**
2. Click **Connect Provider** or **Add Provider**
3. Select **GitHub**
4. Choose the GitHub installation
5. Select the repositories to grant access
6. Authorize the application

![Git provider selection modal](https://forkline.dev/docs/screenshots/connectors/git-provider-modal.webp)

**Why teams prefer it**

- Repository-level access control
- No token rotation burden
- Better rate limits
- Organization-level installation support

> **Important**: The GitHub App requests a fixed permission set. You cannot reduce individual permissions during installation.

### App Permissions

| Permission | Access Level | Purpose |
|------------|--------------|---------|
| Contents | Write | Clone repositories, push commits, create PRs |
| Issues | Write | Read issues, create comments |
| Pull requests | Write | Create PRs, read PR details, comment |
| Checks | Read | Read CI status for auto-fix |
| Actions | Read | Read workflow logs |

### Webhook Events

The GitHub App automatically subscribes to these events:

| Event | Use Case |
|-------|----------|
| Issues | Bot mentions on issues |
| Issue comment | Bot mentions on issue comments |
| Pull request | CI auto-fix, auto review, merge conflict detection |
| Pull request review comment | Bot mentions on PR review comments |

These subscriptions are fixed by the app and cannot be customized per installation.

## GitLab

Use a GitLab git provider when you need GitLab.com or self-managed GitLab support.

1. Go to **Git Providers**
2. Click **Connect Provider**
3. Select **GitLab**
4. Enter your GitLab instance URL
5. Enter a GitLab PAT
6. Save the connector

Optional: set an **Automation Actor Username** if you want Forkline to treat a specific service account as the actor for assignments, review requests, and bot-authored checks.

### Self-Hosted GitLab

For self-hosted GitLab instances:

1. Make sure the instance is reachable from Forkline
2. Create a dedicated automation user or service account
3. Grant it access to the project or group you want Forkline to manage
4. Create a PAT with `api`, `read_repository`, and `write_repository`

```yaml
# Example GitLab service-account PAT setup
Account: forkline-bot
Scopes: api, read_repository, write_repository
```

## Forgejo

Forkline also supports Forgejo, Gitea, and Codeberg instances.

1. Go to **Git Providers**
2. Click **Connect Provider**
3. Select **Forgejo**
4. Enter your Forgejo, Gitea, or Codeberg instance URL
5. Enter a scoped access token
6. Save the connector

Optional: set an **Automation Actor Username** if the service account username you want Forkline to match differs from the token owner.

### Required Scopes

| Scope | Purpose |
|-------|---------|
| `write:repository` | Push branches and update pull requests |
| `write:issue` | Comment on issues and PRs |
| `read:issue` | Read issues and pull request comments |
| `read:user` | Validate connector identity |
| `read:repository` | Clone repositories |
| `read:organization` | Check organization membership for the collaborators trigger policy on organization-owned repositories |

> **Important**: The `read:organization` scope only reveals memberships of organizations the token account itself belongs to. If the token owner is not a member of the repository-owning organization, Forgejo may return only public memberships and private org members will not be recognized. The connector token must be owned by an account that is itself a member of the repository-owning organization for the org-membership fallback to work.

### Self-Hosted Setup

```yaml
# Forgejo/Gitea access token configuration
# Navigate to: Settings > Applications > Access Tokens

Token Name: Forkline
Scopes: read:user, read:repository, write:repository, read:issue, write:issue, read:organization
```

## Managing Git Providers

### Viewing Git Providers

All your git providers appear on the **Git Providers** page. Each card shows:

- Provider type and instance URL
- Connected username
- Repository access scope
- Webhook configuration status

### Disconnecting

To remove a git provider connection:
1. Find the provider card
2. Click the **trash icon** on the card
3. Confirm the action

> **Warning**: Disconnecting a git provider stops runners that depend on repositories from that provider, and related webhooks stop working.

### Webhook Secrets

For GitLab and Forgejo providers, you can add a webhook secret for secure verification:

1. Click the **link icon** on the provider card
2. Enter a secret
3. Configure your git provider with the same secret

```bash
# Generate a secure webhook secret
openssl rand -hex 32
```

On GitLab and Forgejo, a webhook acts only on the repositories registered under its own connector, so each owner adds their own webhook.

## Troubleshooting

### Repository Not Found

If Forkline cannot find your repository:

1. Verify the git provider has access to it
2. For GitHub, confirm the installation includes the repository
3. On GitLab and Forgejo, add your own webhook: tasks no longer arrive through another owner's webhook

### Authentication Failed

If authentication fails:

1. Reconnect the git provider
2. Verify the required scopes are granted

## Next Steps

- [Configure webhooks](https://forkline.dev/docs/automation/webhooks)
- [Start a runner](https://forkline.dev/docs/runners/starting)
- [Set up AI providers](https://forkline.dev/docs/getting-started/ai-providers)