# Connect GitLab, Bitbucket or any git server

> Connect Falak to GitLab, Bitbucket, GitHub Enterprise or any SSH-reachable git server with access tokens, app passwords or deploy keys, plus webhooks.

Source: https://falak.sh/docs/guides/connect-git-tokens/

Besides the [GitHub App](/docs/guides/connect-github/), Falak connects to git providers with credentials you supply. Credentials are verified with the provider before they are saved, stored encrypted, and never shown again.

![Settings → Source control: a table of connections (GitHub via OAuth, a self-managed GitLab via access token, an internal custom git server with deploy keys only), cards to add GitHub, GitLab, Bitbucket or Custom Git connections, and a list of recent push webhooks.](./_images/settings-source-control.png)

## What each connection type does

| Provider | API `provider` | Auth (`auth_type`) | Deploy keys | Push webhooks |
|---|---|---|---|---|
| GitHub (token) | `github` | `token` | Added per site through the API | Created per repository through the API |
| GitLab.com or self-managed | `gitlab` | `token` | Added per site | Created per repository |
| Bitbucket Cloud | `bitbucket` | `basic` (username + app password) or `token` | Added per site | Created per repository |
| Custom git (Gitea, Forgejo, plain SSH) | `custom` | `none` | Per-site deploy key you add yourself | You configure the webhook |
| GitHub App | `github` | `app` | none (HTTPS installation tokens) | One app webhook |

## Connect

  
    Use this for GitHub Enterprise Server, or instead of the GitHub App.

    
    1. Create a fine-grained or classic token with access to repository **contents**, **deploy keys** and **webhooks** (classic: `repo` and `admin:repo_hook`).
    2. **Settings → Source control → GitHub → Use a token**. For GitHub Enterprise, enter your base URL.
    3. Paste the token and save.
    
  
  
    
    1. Create a personal, group or project access token with the **`api`** scope.
    2. **Settings → Source control → GitLab → Use a token**. For self-managed GitLab, enter the base URL (for example `https://gitlab.acme.com`).
    3. Paste the token and save.
    
  
  
    
    1. Create a repository or workspace access token with **repository** and **webhook** scopes, or an app password.
    2. **Settings → Source control → Bitbucket → Use a token**.
    3. Choose token or username + app password, and save.
    
  
  
    
    1. **Settings → Source control → Custom Git → Add server**. Enter the base URL, for example `ssh://git@git.acme.com`.
    2. When you create a site on this connection, enter the repository path or full URL.
    3. Add the site's **deploy key** (shown on the site) to the repository on your git server, read-only.
    4. For push-to-deploy, add a webhook on your git server (see below).
    
    Public repositories need no key.
  

Or through the API:

```bash
curl -X POST https://falak.example.com/api/v1/source-control/connections \
  -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"provider": "gitlab", "auth_type": "token", "name": "GitLab", "base_url": "https://gitlab.acme.com", "token": "glpat-…"}'
```

## Webhooks for custom git servers

Custom git servers have no API Falak can call, so configure the webhook yourself with the URL and secret of the site's webhook. Falak accepts a delivery when **one** of these matches the secret:

| Header | Sent by | Value |
|---|---|---|
| `X-Gitea-Signature` | Gitea | HMAC-SHA256 of the body (hex) |
| `X-Forgejo-Signature` | Forgejo | HMAC-SHA256 of the body (hex) |
| `X-Hub-Signature-256` | GitHub-compatible servers | `sha256=` + HMAC-SHA256 of the body |
| `X-Falak-Token` | Your own script | The secret itself |

The endpoint is `POST https://<panel>/api/webhooks/source-control/<webhook-id>`. Deliveries are limited to 120 per minute per webhook (`FALAK_WEBHOOK_RATE_LIMIT`). Only branch pushes trigger deploys; tag pushes and branch deletions are ignored.

If configuring a webhook is not possible, call the site's [deploy hook](/docs/guides/push-to-deploy/#deploy-hooks) from your CI instead.

## OAuth apps (optional)

Operators can offer "Sign in with GitHub/GitLab/Bitbucket" connections by registering OAuth applications and setting these in `/opt/falak/custom.env`:

| Provider | Variables | Callback URL |
|---|---|---|
| GitHub | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` (`GITHUB_URL`, `GITHUB_API_URL` for Enterprise) | `https://<panel>/source-control/callback/github` |
| GitLab | `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`, `GITLAB_URL` | `https://<panel>/source-control/callback/gitlab` |
| Bitbucket | `BITBUCKET_CLIENT_ID`, `BITBUCKET_CLIENT_SECRET` | `https://<panel>/source-control/callback/bitbucket` |

OAuth requests the scopes `repo admin:repo_hook read:user` (GitHub) and `api read_user` (GitLab).

## Limits

- Bitbucket **Server / Data Center** is not supported (Bitbucket Cloud only).
- OAuth works for only one self-managed GitLab instance (set by `GITLAB_URL`); connect others with tokens.

## Next steps