The GitLab integration allows you to manage your Platform.sh environments directly from your GitLab repository.
- Create a new environment when creating a branch or opening a pull request on GitLab.
- Rebuild the environment when pushing new code to GitLab.
- Delete the environment when merging a pull request.
To manage source integrations, you need to be a project admin.
To integrate your Platform.sh project with an existing GitLab repository, generate a project access token (you can use a personal access token but a project access token has more limited permissions). Note that for the integration to work, your GitLab user needs push access to the repository.
- In GitLab, navigate to the project you want to integrate.
- In the Settings menu, choose Access Tokens.
- Give the token a name such as “Platform.sh Integration”.
- (Optional) set an expiration date.
- Ensure the token has the following scopes:
api(to access your API)
read_repository(to read the repository)
- Create the token.
- Copy the token and save it somewhere (you can’t see it again.).
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.
Run the following command:
platform integration:add --type=gitlab --token=GITLAB_ACCESS_TOKEN --base-url=GITLAB_URL--server-project=NAMESPACE/PROJECTNAME --project=PLATFORM_SH_PROJECT_ID
GITLAB_ACCESS_TOKENis the token you generated in step 1.
GITLAB_URLis the base URL to call the GitLab API. It’s
https://gitlab.comif your repository is hosted on GitLab. Otherwise, it’s the base URL for your GitLab instance.
NAMESPACE/PROJECTNAMEis the namespace of your GitLab repository, not including the base URL.
PLATFORM_SH_PROJECT_IDis the ID for your Platform.sh project.
For example, if your repository is located at
the command is similar to the following:
platform integration:add --type=gitlab --token=abc123 --base-url=https://gitlab.com --server-project=sandbox/application --project=abcdefgh1234567
--build-merge-requests: Track and deploy merge-requests (true by default)
--build-wip-merge-requests: If set to
true, draft merge requests also have an environment created. If false, they’re ignored. If
false, this value is ignored. (
--merge-requests-clone-parent-data: Should merge requests clone the data from the parent environment (true by default)
--fetch-branches: Track and deploy branches (true by default)
--prune-branches: Delete branches that don’t exist in the remote GitLab repository (true by default)
--base-url: Only set if using self-hosted GitLab on your own server. If so, set this to the base URL of your private server (the part before the user and repository name).
Note that the
--prune-branches option depends on
--fetch-branches being enabled.
--fetch-branches is disabled,
--prune-branches is automatically be set to false, even if specifically set to true.
- Select the project where you want to enable the integration.
- Click Settings.
- Under Project settings, click Integrations.
- Click + Add integration.
- On the GitLab integration, click + Add.
- Add the token you generated.
- Optional: If your GitLab instance is not hosted at
https://gitlab.com, enter its base URL.
- Choose the repository to use for the project.
- Check that the other options match what you want.
- Click Add integration.
Verify that your integration is functioning properly using the CLI:
If the integration was added with correct permissions, the necessary webhook is added automatically.
If you see the message
Failed to read or write webhooks, you need to add a webhook manually:
- Get the webhook URL by running
- Copy the
- Go to your GitLab repository and click Settings > Webhooks.
- Paste the hook URL. In the Trigger section select Push events, Tag push events, and Merge request events. Click Add webhook.
You can now start pushing code, creating new branches or opening merge requests directly on your GitLab repository. You see environments get automatically created and updated on the Platform.sh side.
Environments based on GitLab merge requests have their target branch set as their parent on Platform.sh. They’re added as active environments with a copy of the parent’s data.
Environments based on branches always have the default branch set as their parent on Platform.sh. They’re added as inactive environments with no data or services.
You can clone your codebase by running
platform get <projectID>
or in your project in the console by going to Code > Git and running the
git clone command.
When you perform this action, you are actually cloning from your remote integrated repository, if you have the appropriate access to do so.
Your GitLab repository is considered to be the source of truth for the project. The project is only a mirror of that repository and all commits should be pushed only to GitLab.
For merge requests, 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.