Skip to main content
If your GitLab instance is not accessible from the public internet, configure a GitLab CI/CD pipeline that pushes code to Upsun and manages environments via the Upsun API. This method provides full deployment control while keeping your GitLab instance isolated.

​
1. Generate a token

To integrate your Upsun project with an existing GitLab repository, generate a project access token. Ensure the token has the following scopes:
  • api to access your API
  • read_repository to read the repository
For the integration to work, your GitLab user needs push access to the repository and to configure a webhook on a GitLab repository, you need to have Maintainer or Owner user permissions. Copy the token.
To create a project access token, you need to have a sufficient GitLab license tier. If you don’t see Access Tokens under Settings, upgrade your GitLab tier. Alternatively, you can create a personal access token, but that’s attached to a specific user rather than the project as a whole and grants more permissions.

​
2. Enable the integration

To enable the integration, use either the CLI or the Console.
Run the following command:
upsun integration:add \
  --project <VariableBlock name="PROJECT_ID" /> \
  --type gitlab \
  --server-project <VariableBlock name="PROJECT/SUBPROJECT" /> \
  --token <VariableBlock name="GITLAB_ACCESS_TOKEN" /> \
  --base-url <VariableBlock name="GITLAB_URL" />
  • PROJECT_ID is the ID of your Upsun project.
  • PROJECT/SUBPROJECT is the name of your repository in GitLab.
  • GITLAB_ACCESS_TOKEN is the token you generated.
  • GITLAB_URL is the base URL for your GitLab server if you self-host. If you use the public https://gitlab.com, omit the --base-url flag when running the command.
For example, if your repository is located at https://gitlab.com/platformsh/platformsh-docs, the command is similar to the following:
upsun integration:add \
  --project abcdefgh1234567 \
  --type gitlab \
  --server-project platformsh/platformsh-docs \
  --token abc123
In both the CLI and Console, you can choose from the following options:
CLI flagDefaultDescription
fetch-branchestrueWhether to mirror and update branches on Upsun and create inactive environments from them. When enabled, merging on an Upsun environment isn’t possible. That is, merging environments must be done on the source repository rather than on the Upsun project. See note below for details related to this flag and synchronizing code from a parent environment.
prune-branchestrueWhether to delete branches from Upsun that don’t exist in the GitLab repository. When enabled, branching (creating environments) must be done on the source repository rather than on the Upsun project. Branches created on Upsun that are not on the source repository will not persist and will be quickly pruned. Automatically disabled when fetching branches is disabled.
build-merge-requeststrueWhether to track all merge requests and create active environments from them, which builds the merge request.
build-wip-merge-requeststrueWhether to also track and build draft merge requests. Automatically disabled when merge requests aren’t built.
merge-requests-clone-parent-datatrueWhether to clone data from the parent environment when creating a merge request environment.
resources-initfalseTo specify a resource initialization strategy for new containers. Once set, the strategy applies to all the deployments you launch through your source integration. See more information on available resource initialization strategies.
To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches and prune-branches options.

​
Source of truth

​
Sync, fetch, and prune

​
Optional: use a GitLab CI/CD pipeline

If your GitLab instance is not accessible from the internet (e.g. air-gapped or behind a firewall), the GitLab integration process outlined above, based on incoming webhooks, might not be the best option to use. Instead, set up a push-based GitLab CI/CD pipeline that pushes code to Upsun and manages environments using the Upsun API. This setup allows you to:
  • Deploy to production on main branch updates
  • Create preview environments for Merge Requests
  • Clean up environments when branches or MRs are removed
  • Keep your GitLab instance fully private

Detailed walkthrough

For a detailed tutorial of how this works, with code samples and rationale, see this blog post: Synchronize your air-gapped GitLab.You can also find a complete working example of how this works in the Upsun GitHub snippets repository.
Last modified on March 11, 2026