> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/administer/environments/git-based-promotion.md).

# Git-based promotion

How Environments use Git repositories and branches, which Git providers n8n supports, and how to troubleshoot Git connections.

With Git-based promotion, changes travel between n8n instances through a Git repository. Each environment is a repository and branch.

{% hint style="info" %}
**Preview status**

Environments are in Preview and may change in future releases. Try them on test instances before you set them up for your production instances.
{% endhint %}

## What n8n writes to the repository

n8n stores promoted content in an `n8n/` folder at the root of the repository. The folder holds an [n8n package](https://docs.n8n.io/build/manage-workflows/n8n-packages.md). n8n exports it when you promote and imports it when you apply. n8n doesn't change anything outside that folder, so the repository can hold other files, such as CI configuration.

## Direct commits and feature branches

Depending on its settings, the environment an instance promotes changes to either:

* Commits directly to its branch.
* Pushes each promote to a feature branch named `n8n-promotion/<timestamp>`, based on its branch. n8n never force-pushes. For feature branches, the environment's branch must already exist on the Git host.

Instances that apply from the environment read its branch, so they see changes from a feature branch only after someone merges it.

## Providers

A provider holds the details n8n uses to connect and authenticate to your Git host. Several environments on an instance can use the same provider. The provider type decides which features you get:

| Feature                                    | Generic Git                           | GitLab                                                                                     |
| ------------------------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------ |
| Authentication                             | SSH key, or username and access token | Access token                                                                               |
| Pick repositories and branches from a list | No                                    | Yes                                                                                        |
| Promotion reviews                          | No                                    | Yes: GitLab merge requests synced to n8n, with a visual diff of the changes in **Reviews** |

GitHub, Bitbucket, and other Git hosts work through Generic Git, without repository lists or promotion reviews.

## Self-hosted n8n

* If your GitLab instance is on an internal network, allow it for GitLab API calls in [SSRF protection](https://docs.n8n.io/deploy/host-n8n/configure-n8n/security/enable-ssrf-protection.md) with `N8N_SSRF_ALLOWED_HOSTNAMES` or `N8N_SSRF_ALLOWED_IP_RANGES`.
* If your Git host uses a certificate from a private certificate authority, set `GIT_SSL_CAINFO` or `GIT_SSL_CAPATH` for Git, and [configure custom certificate authorities](https://docs.n8n.io/deploy/host-n8n/configure-n8n/basic-configuration/configuration-examples/configure-custom-ssl-certificate-authorities.md) for API calls.
* To get detailed logs, set `N8N_LOG_SCOPES=promotions`.

## Troubleshooting

### Could not complete the Git operation

Check:

* The authentication details in the provider are correct and haven't expired.
* For SSH, the deploy key has write access.
* The branch exists on the Git host.
* The repository URL has the right format for the authentication type. See [Generic Git](https://docs.n8n.io/administer/environments/git-based-promotion/generic-git.md).

## In this section

* [Generic Git](https://docs.n8n.io/administer/environments/git-based-promotion/generic-git.md): connect any Git repository over SSH or HTTPS.
* [GitLab](https://docs.n8n.io/administer/environments/git-based-promotion/gitlab.md): connect GitLab with an access token, and review promotions as merge requests.

## Related resources

* [Environments](https://docs.n8n.io/administer/environments.md)
* [Plan your environments](https://docs.n8n.io/administer/environments/plan-your-environments.md)
* [Your first promotion](https://docs.n8n.io/administer/environments/first-promotion.md)
* [Promote changes](https://docs.n8n.io/administer/environments/promote-changes.md)
* [Apply changes](https://docs.n8n.io/administer/environments/apply-changes.md)
* [Promotion reviews](https://docs.n8n.io/administer/environments/promotion-reviews.md)
* [Known limitations](https://docs.n8n.io/administer/environments/known-limitations.md)
* [Upgrade from Environments (Classic)](https://docs.n8n.io/administer/environments/upgrade-from-environments-classic.md)
