# Manage Git integrations

Connect your Git accounts to Northflank so you can build and deploy from your repositories.

You can connect multiple accounts from GitHub, GitLab, Bitbucket, and other supported Git services. You can also connect a self-hosted Git service.

## Add a Git account

You can connect a Git account to your team from the **Integrations** section in your team dashboard.

> [!note]
>
> [Click here](https://app.northflank.com/s/account/integrations/vcs) to connect a Git account.

1. In your team dashboard, click **Integrations**.

2. Click **Git**.

3. Click **Link** next to the Git service you want to connect.

4. Follow the instructions for the Git service.

For GitHub, choose the user or organization account for the app installation. For [Cursor Origin](https://northflank.com/docs/v1/application/getting-started/link-your-git-account#link-cursor-origin), choose the Cursor namespace and its repository access. For GitLab, Bitbucket, and Azure DevOps OAuth connections, Northflank connects the account you are signed in to.

Once connected, you can use repositories from the account to build and deploy services on Northflank.

## Add a self-hosted VCS

You can connect a Git provider hosted on your own infrastructure.

> [!note] Requirements
>
> You will need the following to get started:
>
> - Permission to manage Git integrations in your Northflank team
> - An HTTPS root URL, such as `[https://git.example.com](https://git.example.com)`
> - Permission to create the provider's OAuth application or GitHub App
> - Network access for Northflank to read the provider API and clone repositories
> - Network access for the Git host to deliver webhooks to Northflank

Webhooks notify Northflank when repository events occur, so configured builds and workflows can run automatically.

> [!note]
>
> [Click here](https://app.northflank.com/s/account/integrations/vcs) to add a self-hosted VCS.

1. Open your team's Integrations → Git page.

2. Select Add a self-hosted VCS.

3. Enter a name for the integration.

4. Enter your Git host's root URL under VCS provider URL.

Continue with your provider below. Once connected, you can [build from your repositories](https://northflank.com/docs/v1/application/build/build-code-from-a-git-repository) and [manage the integration](https://northflank.com/docs/v1/application/collaborate/manage-git-integrations#self-hosted-vcs-settings).

### Add a self-hosted GitLab instance

1. Select GitLab Enterprise Edition or Community Edition in Northflank.

2. Create an OAuth application on your GitLab host at `/-/user_settings/applications`. Administrators can also use `/admin/applications`.

3. Give the application the `api` scope.

4. Enable its Confidential control.

5. Set its redirect URI to the exact value shown in Northflank.

6. Enter its Application ID and Secret in Northflank.

7. Select Submit.

8. Authorize Northflank with the GitLab account that can access your repositories.

See [GitLab's OAuth application guide](https://docs.gitlab.com/integration/oauth_provider/) for more details.

### Add Gitea or Forgejo

Gitea and Forgejo use the same connection flow. Northflank requests read and write access to repositories, including webhooks and commit statuses. The linked account needs repository owner or administrator access to manage webhooks.

Before authorizing access, review the permission behavior for [Gitea](https://docs.gitea.com/development/oauth2-provider/) or [Forgejo](https://forgejo.org/docs/latest/user/authentication/oauth2-provider/).

1. Select Gitea / Forgejo in Northflank.

2. Create an OAuth2 application at `/user/settings/applications` on your Git host.

3. If the provider offers a client-type choice, select a confidential client.

4. Set its redirect URI to the exact value shown in Northflank.

5. Enter its OAuth client ID and OAuth client secret in Northflank.

6. Select Submit.

7. Authorize Northflank with the Git account that can access your repositories.

### Add GitHub Enterprise Server

You need permission to create and install a GitHub App for the selected user or organization. App creation and repository installation are separate steps.

The app requests read and write permissions. Before approving installation, review the requested access on GitHub.

1. Select GitHub Enterprise in Northflank.

2. Choose User or Organisation under GitHub App location type.

3. For Organisation, enter the organization name under Application namespace.

4. Select Submit to start GitHub App creation.

5. Complete app creation on your GitHub server.

6. Return to your team's Integrations → Git page.

7. On your self-hosted integration, select Link to start app installation on GitHub.

8. Choose the repositories that the app can access.

9. Complete the installation.

## Self-hosted VCS settings

Open Integrations → Git in your team dashboard. Select the configuration button  on your self-hosted provider.

To change the Git host address, edit VCS provider URL. Select Update self-hosted settings to save it.

For a verified integration, Edit application lets you replace its credentials. Changing Application ID requires the matching Client secret. Leave secret fields blank to keep their current values.

GitHub Enterprise also provides Webhook secret and PEM file, the GitHub App's private key.

> [!warning]
>
> Before changing the application ID or client secret, plan to relink all accounts that use this integration. Saving those credentials unlinks the existing accounts.

1. Select Edit application.

2. Enter the changed credentials for your provider.

3. Select Update self-hosted settings.

4. If you changed the application ID or client secret, relink the affected Git accounts.

### Troubleshoot a self-hosted connection

| Symptom | Action |
| --- | --- |
| OAuth authorization fails | Make sure that the redirect URI and application credentials match the values in Northflank. |
| GitHub App setup remains pending | Select Create GitHub App to resume setup. After creating the app, link the account to install it. |
| A repository is missing | Make sure that the linked account or app installation has access. Then refresh Connected repositories. |
| Automatic builds do not start | Inspect webhook delivery, repository permissions, and your [build rules](https://northflank.com/docs/v1/application/build/build-code-from-a-git-repository#build-specific-branches-or-pull-requests). |

For GitLab, Gitea, and Forgejo, the linked account page offers Repository webhooks controls to regenerate webhook tokens. GitHub Enterprise uses its GitHub App configuration instead.

## Restrict repository access

You can restrict which repositories team members can access when connecting Git accounts to Northflank.

For GitHub and GitHub Enterprise Server, choose repository access when installing the GitHub App on a user or organization account.

For GitLab, self-hosted GitLab, and Bitbucket, you can restrict access to specific namespaces from the linked account's configuration in Northflank.

For Gitea and Forgejo, repository access follows the linked Git account's permissions. Northflank does not offer a namespace restriction control for these providers.

For [Cursor Origin](https://northflank.com/docs/v1/application/getting-started/link-your-git-account#manage-cursor-origin-access), choose all repositories or selected repositories during installation. Use Update installation to change access for the same Cursor namespace.

## Next steps

- [Build from a Git repository: Start building from your linked Git repositories in minutes.](/v1/application/build/build-code-from-a-git-repository)
- [Run an image continuously: Deploy a built image as a continuously-running service.](/v1/application/run/run-an-image-continuously)