# Source control API

> List and create Falak git connections for GitHub, GitLab, Bitbucket and custom git servers through the REST API.

Source: https://falak.sh/docs/api/source-control/

## `GET /api/v1/source-control/connections` — `source_control.view`

Lists the organization's git connections, including GitHub App connections. Credentials are never returned. Use a connection's `id` as `source_connection_id` when you create a site.

## `POST /api/v1/source-control/connections` — `source_control.manage`

| Field | Rule |
|---|---|
| `provider` | `github`, `gitlab`, `bitbucket` or `custom` |
| `auth_type` | `token`, `basic` (Bitbucket username + app password) or `none` (custom git) |
| `name` | Optional display name |
| `base_url` | Self-managed GitLab, GitHub Enterprise, or the custom git server |
| `token` | For `token` |
| `username`, `password` | For `basic` |

Tokens are verified against the provider before saving. Credentials are write-only.

```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": "github", "auth_type": "token", "name": "GitHub (bot)", "token": "github_pat_…"}'
```

```bash title="Custom git over SSH"
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": "custom", "auth_type": "none", "name": "Internal git", "base_url": "ssh://git@git.acme.test"}'
```

Custom git uses public URLs or per-site deploy keys.

GitHub App connections (`auth_type: app`) can only be created in the browser (**Settings → Source control → Connect GitHub**), because GitHub asks the user to confirm the app and pick repositories. See [Connect GitHub](/docs/guides/connect-github/).

## Webhook endpoints

These receive pushes from providers; you do not call them yourself:

| Endpoint | Verified by | Limit |
|---|---|---|
| `POST /api/webhooks/source-control/github-app/{app-id or env}` | `X-Hub-Signature-256` with the app's secret | 600/min per app |
| `POST /api/webhooks/source-control/{webhook}` | Provider signature or token (see [custom git webhooks](/docs/guides/connect-git-tokens/#webhooks-for-custom-git-servers)) | 120/min per webhook |