Skip to main content

Pull files from GitLab and create pull requests from Lokalise.

Nick Ustinov avatar
Written by Nick Ustinov
Updated over a week ago

Use this app to exchange files with your GitLab repository

As soon as the app is set up, you can pull the files manually via the Lokalise web dashboard or set up an automatic pull so that the files are imported automatically as they are pushed to GitHub by your developer team.

Once the translations are completed, you can trigger the creation of a pull request on GitHub via the Download page.


1. Connect your repository

Please note that you can also use project access tokens instead of personal ones.

Open your Lokalise project and navigate to Apps:

Find GitLab in the list, click Install and then Connect.

You will need to generate and copy/paste a personal access token from GitLab. Proceed to Gitlab. Click on your avatar in the top right corner and click Preferences. Check that your user has permissions for project administration and setting management.

Next click Access tokens, click Add new token, enter the new token's name and make sure to enable the api scope.

Click Create personal access token. You will be presented with a token — make sure to copy it as you won't be able to view it after closing the page.

Return to Lokalise and paste your token into the Personal access token field. Also enter the Host URL (usually it's just After doing that, you will be able to enter your Project ID and Branch to pull from. Optionally, provide a Project name. If the name is provided, it will be displayed when choosing Gitlab app on the Download page (see below).

You can find your Project ID by proceeding to GitLab, opening your project, and clicking More actions button:

Also, you'll need to choose at least one platform in the Include in exports for field. As you export files from Lokalise, you can trigger the GitLab app to create pull requests to repositories with a platform related to the exported file format.

Finally, it is important to decide whether you would like the filenames to include a full path. It is not needed in most cases, as you can configure the directory structure prefix at the pull request creation (export) step. However, when you have similar files in different subfolders, e.g. admin/locale.json  and frontend/locale.json, you need to enable the Include path in the filenames option. Keep in mind that if you already have files uploaded to the project, including a path in the filenames at this step would mean that you are uploading different files.

2. Select files to pull

Browse the selected project and select the files you want to pull and import.

In most cases, in this step you would only need to select the base language files (the files that are being modified locally and then pushed to GitLab). After selecting a file, you must set the language of the file in the dropdown menu.

3. Add more repositories

As we recommend keeping all platform files within the same project, you may want to set up other repositories that apply to the same project. Click Add another repo to add more repositories.

Pulling files

Manual pull

Use the Pull now button on the app page. Clicking the button will add the pull to the system queue to be executed in the background.

If you need to adjust the options, click Pull options on the app page:

These options are similar to the ones presented on the Upload page.


When you are satisfied with the initial pull results, it is a good idea to set up a webhook at GitLab which automates pulling the changes to Lokalise as you push to GitLab. 

In GitLab, navigate to your repository settings > Webhooks:

Click Add new webhook. Copy/paste the Auto-pull URL provided in the Lokalise app config into the URL field. Also paste the Auto-pull secret generated on the app page into the Secret token field. Enable Push events trigger.

Please note that currently we are in the process of migrating all auto-pull URLs from to subdomain. Thus, on the app's page you may still see specified for the auto-pull URL but it is very much recommended to change it to when pasting to GitLab.

Click Add webhook to finalize creation.

Pull requests

To create a new pull request on GitLab with all the changes made on Lokalise, proceed to the Download page and find the App triggers section. Enable the GitLab option and choose your repository:

If the Repository name has been provided during the initial setup, you'll see it in the dropdown.

It is a good idea to use the Preview button first, so you can see the resulting file/folder structure before triggering the creation of a pull request.

We would recommend triggering pull requests only to the repos of the platform that match the file type you are exporting, i.e. if you are exporting in a JSON format, Lokalise will only create pull requests in repositories with the Web platform.

To actually create a pull request on GitLab, you should press Build only (this way you won't download a translation bundle to your local PC). To check the status of the pull request creation, return to the GitLab app page and click the Logs button.

Here is what happens after you trigger a new PR:

  • A new branch is created from the last revision of the branch you chose in the app setup. The branch name would look like this:  lokalise-2018-03-12_15-14-13.

  • A commit with all the files is created in the new branch.

  • A pull request from the new branch to the previously chosen branch is created.

You may then review and merge a pull request in GitLab.

To initiate a pull request from the API, use the triggers=['gitlab']  parameter with the Download files endpoint. If you are using the CLI tool, use --triggers=gitlab  as a parameter when performing the export.

If there is a firewall in place, make sure to whitelist IP addresses listed in the Webhooks article.

Did this answer your question?