To use the Smartling GitHub Connector, you must connect your Smartling project(s) to your GitHub account. There are two authentication types you can choose from when creating a Configuration Set:
The GitHub App is generally preferred over the OAuth model, as it provides a more modern, secure, and scalable way of connecting your Smartling account to GitHub.
Setting up with OAuth App
With the OAuth App, a dedicated GitHub service user account must be created for the Connector. To ensure the Connector's correct functioning, admin rights must be granted to the service user account powering the Connector, allowing access to all repositories used for localization purposes. Acting as an admin in your GitHub account also allows Smartling to create webhooks for each Configuration Set, which the Connector requires to detect activity containing content for translation.
Since the OAuth App relies on a dedicated GitHub admin account for authentication, access to this user account is required whenever a new Configuration Set is created in your projects (for example, to configure a new repository or branch for translation).
Tip: Click here for a step-by-step guide to setting up the GitHub Connector with OAuth App.
Setting up with GitHub App (recommended)
GitHub Apps provide more flexibility, as they are not tied to a specific user account.
With GitHub Apps, granting admin rights to the Smartling Connector (or a related user) is no longer necessary. Instead, this authentication model offers a higher level of security by giving you granular control over the repositories you would like to share with Smartling. During installation, you will also see a list of the permissions requested by the Smartling GitHub App.
In Smartling, GitHub Apps must be configured only once per GitHub Organization, under your Account Settings > Integrations > GitHub. Once an authorization is in place that links your Smartling account to your GitHub organization(s), any new Configuration Sets created using GitHub App authentication will be able to communicate with GitHub automatically.
Each Configuration Set for the Connector can then be managed and created autonomously. This allows Smartling users to maintain the Connector configuration without having direct access to your GitHub Organization.
As GitHub Apps offer higher rate limits than the OAuth App method, they allow our Connector to operate without the possibility of being temporarily throttled.
Tip: Click here for a step-by-step guide to setting up the GitHub Connector with GitHub App.
Migrating from OAuth App to GitHub App
In your Github Connector Project, navigate to the Settings tab > Github Settings.
Next to each Configuration Set, which still uses the OAuth App, is a link that allows you to migrate to GitHub App authentication.
Before you start any migration, you should follow the instructions for installing and authorizing the Smartling GitHub Connector App in GitHub. Additionally, your configuration set must be disabled before migrating to GitHub App authentication.
Once you have taken these steps, the migration is a simple process of checking that there is an authorization in place for the relevant target organization and that it contains the repository and branch referenced by the Configuration Set.
If, for example, the referenced repository is not accessible to our GitHub App, you will need to update the permissions in GitHub to grant access. You will not be able to proceed until all items in the readiness check reflect a positive status.
Once completed, this migration cannot be undone, and the switch from the OAuth App is permanent for the affected Configuration Set.