1. Help Center
  2. Phrase for developers
  3. Using version control systems with Phrase

GitLab Sync

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


GitLab Sync relies on the .phrase.yml configuration file being present in your GitLab repository to know which locale files you want to sync with Phrase.

This is the same file that the command-line Phrase Client uses, and it defines which files you want to import (push) and export (pull). See the documentation to learn more about how to set up your Phrase configuration file.

To ensure API compatibility, use GitLab 9.5 or newer.

Connect your project

Once your completed configuration file is in place, you can connect your repository to Phrase:

  1. Go to the Phrase Integrations page. In the GitLab Sync entry, click Configure.
  2. Click on Add GitLab Sync to create a new sync entry.
  3. Choose the Phrase project you want to sync with GitLab.
  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. Choose the GitLab repository you want to sync with Phrase.
  6. Choose the repository branch you want to import (push) from and export (pull) to. Usually, this is the “main” branch.
  7. Click Validate Configuration to check if your access token and configuration file are set up correctly.
  8. Click “Save settings.”

Your project is now connected to your GitLab repository.

Import files

To import your locale files to Phrase from your connected GitLab repository, follow these steps:

  1. Go to the Phrase Integrations page, then open the GitLab Sync page.
  2. Choose the project you want to sync and click Import.
  3. Phrase imports your GitLab data to your Phrase project.

Turn on Auto-Import

You can use Auto-Import to automatically import files to Phrase after every commit to GitLab. To turn it on, follow these steps:

  1. Go to the Phrase Integrations page. Then, choose GitLab Sync and click Configure.
  2. Choose your Phrase project, click More, and then choose Configure.
  3. Enable the Auto-Import option in the settings that appear.
  4. Click Save Settings.
  5. Phrase generates a payload URL and secret token. When they appear, copy them to the clipboard.
  6. Click Save.

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

  1. Go to the settings for your GitLab repository and choose Integrations.
  2. Add a new webhook with the following settings:
    • URL: Paste your generated payload URL. 
    • Secret Token: Paste your secret token.
  3. Click “Add webhook.”

After setting up Auto-Import for your Phrase project, Phrase will import locale files from your repository after every update pushed to the repository branch you chose (usually “main”).

Export files

To export the most recent locale files to your repository, follow these steps:

  1. Go to the Phrase Integrations page. Then, open the GitLab Sync page.
  2. Choose the project you want to sync and click Export.
  3. After a few seconds, Phrase exports your most recent locale files to your GitLab repository as a new pull request

Once Phrase is done exporting files, you can go to your GitLab repository to merge (or close) the pull request. Remember to delete the branch when you finish.


Gitlab Sync keeps a history of the lastest imports and exports for each Phrase project. Follow these steps to view the history:

  1. Go to the GitLab Sync overview page.
  2. In the entry for the project whose history you want to view, click More. Then, choose History.

The import and export history for the project appears. Export entries in the history include a link to the corresponding merge request.

Why a pull request?

Phrase delivers locale file updates as pull requests so that you can review all the changes. This keeps you in control of what actually goes into the branch you chose (usually “main”).

Self-hosted GitLab

GitLab Sync also supports the self-hosted version of GitLab. To sync with a self-hosted GitLab  instance, select the “GitLab self-hosted” checkbox in the sync settings and add the API URL to an Enterprise instance. Make sure that the API endpoint is publicly reachable from Phrase.




The validation fails, but the configuration file seems correct

Make sure that your configuration file includes at least one pull target (for importing into Bitbucket) and one push target (for exporting into Phrase). Double-check that the project ID is valid and belongs to the Phrase project you want to sync your files with. Please also note, that the GitLab sync currently only works with one project per configuration file which needs to be defined in the file header.

Nothing gets imported or exported

Make sure that your .phrase.yml configuration file contains valid pull and push targets. Note that many file formats require locale_id to be defined for each source, since the files don’t contain any locale information. You can always use the Phrase Client to check if your configuration file behaves as you expect.

GitLab Sync still doesn’t work

Contact us — we’re happy to help.

Further reading