Integrate with GitLab
Back to home
On this page
If you have code in a GitLab repository, you might want to connect it to a Platform.sh project. This means you can keep your GitLab workflows and treat the GitLab repository as the source of truth for your code.
Your Platform.sh project becomes a mirror of your GitLab repository. This means you shouldn’t push code directly to Platform.sh. Any changes you push directly get overwritten by the integration when changes happen in the GitLab repository.
When you set up an integration with GitLab, it automates the following processes for you:
- Creating a new environment when a branch is created or a merge request is opened.
- Rebuilding the environment when new code is pushed to GitLab.
- Deleting the environment when a merge request is merged.
Before you begin
To manage source integrations, you need to be a project admin.
You also need a GitLab repository with working code.
1. Generate a token
To integrate your Platform.sh project with an existing GitLab repository, generate a project access token. Ensure the token has the following scopes:
api
to access your APIread_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.
Note
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:
platform integration:add \
--project PROJECT_ID \
--type gitlab \
--server-project PROJECT/SUBPROJECT \
--token GITLAB_ACCESS_TOKEN \
--base-url GITLAB_URL
PROJECT_ID
is the ID of your Platform.sh 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 publichttps://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:
platform integration:add \
--project abcdefgh1234567 \
--type gitlab \
--server-project platformsh/platformsh-docs \
--token abc123
- Select the project where you want to enable the integration.
- Click Settings.
- Under Project settings, click Integrations.
- Click + Add integration.
- Under GitLab, click + Add.
- Add the token you generated.
- Optional: If your GitLab project isnโt hosted at
gitlab.com
, enter your GitLab custom domain. - Click Continue.
- Choose the repository to use for the project.
- Check that the other options match what you want.
- Click Add integration.
In both the CLI and Console, you can choose from the following options:
CLI flag | Default | Description |
---|---|---|
fetch-branches |
true |
Whether to track all branches and create inactive environments from them. |
prune-branches |
true |
Whether to delete branches from Platform.sh that donโt exist in the GitLab repository. Automatically disabled when fetching branches is disabled. |
build-merge-requests |
true |
Whether to track all merge requests and create active environments from them, which builds the merge request. |
build-wip-merge-requests |
true |
Whether to also track and build draft merge requests. Automatically disabled when merge requests arenโt built. |
merge-requests-clone-parent-data |
true |
Whether to clone data from the parent environment when creating a merge request environment. |
To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches
and prune-branches
options.
3. Validate the integration
Verify that your integration is functioning properly using the CLI:
platform integration:validate
Add the webhook manually
If the integration was added with the correct permissions, the necessary webhook is added automatically. If you see a message that the webhook wasn’t added, add one manually.
To configure a webhook on a GitLab repository, you need to have Maintainer or Owner user permissions.
-
Get the webhook URL by running this command:
platform integration:get --property hook_url
. -
Copy the returned URL.
-
In your GitLab repository, click Settings > Webhooks.
-
In the URL field, paste the URL you copied.
-
Under Trigger, select Push events and Merge request events.
-
Click Add webhook.
You can now start pushing code, creating new branches, and opening merge requests directly in your GitLab repository. Your Platform.sh environments are automatically created and updated.
Environment parent and status
When a branch is created in GitLab, an environment is created in Platform.sh with the default branch as its parent. It starts as an inactive environment with no data or services.
When a merge request is opened in GitLab, an environment is created in Platform.sh with the merge request’s target branch as its parent. It starts as an active environment with a copy of its parent’s data.
Source of truth
When you add an integration, your GitLab repository is considered to be the source of truth for the project. Your Platform.sh project is only a mirror of that repository and you should only push commits to GitLab. Any changes you push to Platform.sh get overwritten by the integration when changes happen in your GitLab repository.
To clone your code, follow these steps:
Run the following command:
platform get PROJECT_ID
- In the Console, open the project you want to clone.
- Click Code.
- Click Git.
- Run the command you find using Git.
When you do this, you're cloning from your integrated GitLab repository, if you have the appropriate access to do so.
Merge request URLs
When a merge request is deployed, the integration reports the primary URL for the deployed environment. So you get a link to the deployed environment right in the merge request.
If you have multiple routes, ensure the correct one is reported by specifying the primary route.