The following article outlines important prerequisites and some best practices for the GitHub Connector.
Hosting
The GitHub Connector is incompatible with self-hosted repositories, i.e., GitHub Enterprise Server. However, GitHub Enterprise Cloud or any other plan type that is hosted on github.com, is compatible with the connector.
Authentication Users
To authenticate Smartling in GitHub, the authentication user must be an Admin on the repository and a member of your GitHub Organization. This is because the connector requires the "Change a repository's settings" permissions to add and remove our webhooks. If the permissions are changed after the GitHub Connector has been installed, it will lead to errors and unexpected behavior from the GitHub Connector.
It is important to note that Smartling cannot validate the user permissions in GitHub. This means that a non-Admin user could attempt to add a configuration set in Smartling for a repository, but the connector won't be able to "see" that repository if the user is not an Admin in GitHub. This often results in content not being ingested, and the connector appears to be "not working" as expected.
Best Practices
Dedicated User
We recommend that you create a dedicated GitHub Admin user to integrate with Smartling, such as smartling@your_business_email.com.
A dedicated user account for the integration will make it easier to track actions in the logs, should an issue arise, as actions made by the connector won't appear to come from a developer. It also prevents disruptions to your integration if the original user account becomes deactivated for any reason.
Log In to One Organization
When creating configuration sets, log in to GitHub as an Admin in one Organization. The configuration set relies on OAuth for authentication, so the user must be logged into GitHub as a member AND an Admin in the repository when creating the configuration set. If the configuration set is created while logged in as different accounts, multiple configuration sets could be created which would rely on different accounts.
When a new member is added to the GitHub Organization, a configuration set must be created in Smartling for that user's repository
Tip: For steps on how to change the authenticated GitHub user, read our documentation on Changing Authentication Users on The GitHub Connector.
Authorization
2FA works with the connector and is used during the initial authentication when setting up a new repository or altering the GitHub Admin user who connects a repository to Smartling. After that initial authentication, the connector works as an OAuth App and operates with an OAuth token and therefore, it won't require 2FA.
Once Smartling has been given access to your GitHub account through the OAuth flow, your GitHub Org member/Repo Admin might need to authorize it. This may be necessary if your GitHub account was created by a third-party application.
To authorize the connector:
- Go to your GitHub Settings > Applications > Authorized OAuth Apps
- Select Smartling GitHub Connector and then select "request access"
- While the owner is granting access, the connector's status will show as "Access request pending". During this time, the connector will not be able to connect
Branches
Content branch names must not begin with "Smartling" as the Connector interprets branches starting with "smartling-" as self-created ones with translations, and will not monitor changes in them.
Best Practices
We recommend connecting to a branch where features or other branches are merged to ensure all strings are correctly captured for translation. For most users, dev and main (master) branches are the common choices.
To avoid any localization issues affecting the main branch, it is recommended to create an additional branch, such as a dev branch, for Smartling to return translations to before the main branch is updated. If you already have a process where localization happens in a separate branch, you can choose that branch instead.
If you feel that any of the above may not be compatible with your development process, see Options for Automation with Source Repositories for an overview of other options.
Tip: For more information on branches, read our documentation on Branch Strategy.