Overview

This page illustrates how the GitHub Connector is able to monitor and create projects based on changes that happen in a set of GitHub repositories.

General Purpose

The GitHub Connector monitors specific files in GitHub repositories, given a certain time interval. Usually in localization projects, common files are JSON, YML, XLIFF, XML, STRINGS or any other structured and predictable format. By comparing the file hash against a repository of previously executed translations for that same file, if a change is detected, a new project will be created and the translation projects starts.

Monitoring Strategies

We can monitor GitHub repositories using its REST API. In order to do so, our clients need to authorize an account to create a token in Bureau Works to access the API. These credentials are encrypted with AES 256 and stored in the Client's profile.

There are two monitoring strategies: branches and pull requests.

Branches

The Connector will constantly monitor one or more branches in one or more repositories, and once the files being observed are modified, it will create a project in Bureau Works and notify our team. In continuous localization projects, any previously translated strings are fully taken into account.

Once a project is delivered, the GitHub Connector will create a Pull Request for a patch branch containing the file(s) after the translation is finished. We can customize the output path and naming strategies for the output files. This creates a non-intrusive and very elegant delivery mechanism when a team tends to use one or just a few branches for development.

Pull Requests

Just like the Branch strategy, we can also monitor Pull Requests, for teams using Gitflow or similar workflows. The Connector can monitor all pull requests, for all the branches, for the same configured files. Again, once a difference is found based on the file's hash, a project will be created.

The big difference with this strategy is the delivery mechanism. Because pull requests refer to a branch, once a project is delivered, the Connector will create a commit in the same branch as the pull request. Once the pull request is accepted and merged, it will carry along the translated file(s) onto the target branch, i.e., master, develop, etc.

Authorize Bureau Works

In order to setup the GitHub Connector, the first thing you have to do is to authorize Bureau Works to access your repositories. As an extra layer of security, we recommend that you create a user that will have exclusive access to the repositories of interest within your organization.

If you can't see the GitHub authorization workflow, you may not have the appropriate roles applied to your account. Please reach out to your organization contact, or if that person is you, please send us an email at help@bureauworks.com.

1. Open My Account on the top-right corner of your Bureau Works view.

2. On the top bar, select Connect GitHub

3. Sign-in to GitHub using the account that you want to connect to Bureau Works.

4. GitHub will send you back to Bureau Works and show a message if the authentication is successful.

Providing Monitoring and Delivery Paths

Once you authorize Bureau Works, you need to provide us with paths of file(s) and repositories that need monitoring. For example, in iOS projects, it's common to have a file called Localizable.strings deployed in each language folder, for example:

en.lproj/Localizable.strings    # Source
pt-BR.lproj/Localizable.strings # Target A
de.lproj/Localizable.strings    # Target B
...

We need to determine which one is the source files, and what are the desired paths to deliver the translations. Every delivery performed by the GitHub connector, depending on the selected strategy, will place the files in the correct folder structure in the GitHub repository.

This step is performed by our team, and is managed via our support at help@bureauworks.com.

Security and Privacy

Each GitHub Connector instance is Client-exclusive, it runs in a separate container and can only access the GitHub token bound to the Client's profile in Bureau Works. Once a token is created, it will grant Bureau Works access to public and private repositories within that organization, in order to properly create pull requests and commits.

Our team does not have access to the encrypted token, and therefore we cannot access the repositories via API. We do provide a detailed audit trail for usage, if needed, and the GitHub system also keeps track of the token usage.