1. Help Center
  2. Phrase for Developers
  3. How to use Version Control with Phrase

GitLab Sync

Phrase GitLab Sync lets you sync your Phrase projects with your GitLab repositories easily.


In order to identify which locale files you want to sync with Phrase, we rely on the .phraseapp.yml  configuration file being present in your GitLab repository.

Since we are using API V4 endpoints we suggest GitLab 9.5 as the minimum required version.

The file is used with the Phrase CLI client and defines which files you want to import (push) and export (pull). See the here to learn more about how to set up your Phrase configuration file.

Connect your project

If you have set up and uploaded your configuration file to GitLab, it’s time to connect your repository to Phrase:

  1. Go to the Integrations Page, Scroll to the GitLab Sync entry and click on configure
  2. Click on “Add GitLab Sync” button in order to create a new sync
  3. Start creating a new GitLab sync by selecting your Phrase project
  4. Enter a personal access token for your GitLab account. You can create an access token in your GitLab Settings. Make sure the access token has the api scope.
  5. Select the GitLab repository you want to sync with Phrase.
  6. Select the repository’s branch used to import (push) and export (pull) your locales (usually ‘master’)
  7. Click Validate Configuration to check if your access token and the configuration file is set up correctly.
  8. Click Save Settings.

 Your project is now connected to your GitLab repository!


Importing your locale files to Phrase from your connected GitLab repository is easy:

  1. Go to the Integrations page and open the GitLab sync page
  2. Choose the project you wish to sync and click on Import.
  3. Your GitLab data will now be imported to your Phrase project.


You can also import your locales to Phrase after every commit to GitLab with Auto-Import:

  1. Go to the Integrations Page, choose GitLab Sync and click on Configure
  2. Select your Phrase project and click on More and choose Configure.
  3. Enable the auto import option in the settings dialog.
  4. Click on Save Settings.
  5. Copy the generated payload URL and secret that will be displayed in the modal dialog.
  6. Click Save.

Next, add a webhook to your GitLab repository in order to notify Phrase of new pushes:

1. Go to your GitLab repository’s Settings section and select Integrations.

2. Add a new webhook:

  • URL: Paste your generated payload URL. 
  • Secret Token: Paste your secret token

3. Click Add webhook

You have successfully activated Auto-Import for your Phrase project and we will import locale files from your repository after every update pushed to the selected branch (usually ‘master’) of your repository.


Exporting the most recent locale files to your repository is just one click away:

  1. Go to the Integrations page and open the GitLab sync page
  2. Choose the project you wish to sync and click on Export.
  3. After a few seconds, your most recent locale files are exported to your GitLab repository as a new pull request

You can now head over to your GitLab repository in order to merge (or close) the pull request. Don’t forget to delete the branch after that.


Each Gitlab  Sync comes with a history of the lastest imports and exports for a specific Phrase project.

  1. Go to the GitLab sync overview page
  2. Please click on the “More” button and choose “History” for your project of choice
  3. You will find an overview of all imports and exports
  4. For all exports, you will find a matching link to the merge request.

Why a pull request?

We’re delivering locale file updates as pull requests so that you can review all changes and thus remain in charge of what actually goes into your selected branch (usually ‘master’).

GitLab self-hosted

GitLab Sync also supports the self-hosted version of GitLab. To sync with a self-hosted GitLab  instance you need to enable GitLab self-hosted in the sync settings and add the API URL to an Enterprise instance. Please make sure that the API endpoint is publicly reachable from Phrase.



The validation fails although the configuration file seems correct, what's wrong?

Make sure you have set up at least one push source and one pull target entry in your configuration file. Double-check if you have entered a valid Project ID and that the Project ID belongs to the Phrase project you want to sync your files with.

Why does nothing get imported?

Please make sure that your .phraseapp.yml configuration file contains valid push sources. Note that a lot of file formats require the locale_id to be defined for each source since they don’t contain any information on the locale in the file itself.

You can always use the Phrase CLI Client in order to check if your configuration file behaves as you expect.

We currently do NOT support placeholders like <locale_name> in this particular case, please specify a static file path like

 - file: ./config/locales/en.yml

It still doesn’t work?

Contact us — we’re happy to help.

Further reading