Setting Up the GitHub Connector with OAuth App

 

This article shows the OAuth App authentication method.
As a more secure and scalable way of working with GitHub, we would recommend using our GitHub App. For more information, see our documentation on Types of Authentication.

Info: This article is for Smartling Account Owners and Project Managers and GitHub Organization members on how to set up the GitHub Connector.

Please note that this Connector is a paid product. For pricing information, please reach out to your Smartling Customer Success Manager.

STEP ONE: Create a GitHub Connector Project in Smartling 

Follow the steps documented in How to Create a Project to set up a GitHub Connector Project in Smartling. Ensure that all languages, workflows, team members and linguistic assets are set up correctly.

STEP TWO: Create a Dedicated GitHub User

GitHub's users are associated with GitHub repositories in a Configuration Set in Smartling. For this reason, we recommend creating a dedicated user account for the GitHub Connector, which is not used for any other activities within your repository, 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.

Note: The GitHub Connector relies on this dedicated user account being a GitHub organization owner or member and having admin access to the repository.

 

How to Create a GitHub Member

1. Follow the steps outlined in GitHub's documentation on how to invite members to your organization
2. Add repositories to be localized to the team
3. Ensure the team has admin access to the repository, by selecting Admin from the user role dropdown for each repository.

Admin Permissions

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 user permissions are changed after the GitHub Connector has been installed, this 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 uploaded to Smartling, and the Connector appears to be "not working" as expected.

Log In to One Organization

When using OAuth for authentication, the user must be logged into GitHub as a member of one Organization AND an Admin in the repository when creating a 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.

Note: To summarize, the dedicated email address must be a GitHub Organization owner/member, a repository admin, and logged into one GitHub Organization when setting up or modifying the Connector configuration.

 

STEP THREE: Authorize Smartling in GitHub

2FA works with the Connector and is used during the initial authentication, when setting up a new repository, or when altering the GitHub Admin user who connects a repository to Smartling. After this initial authentication, the Connector works as an OAuth App and operates with an OAuth token, and, therefore, it won't require 2FA. 

Tip: We recommend setting up a specific Admin user to implement the integration so that actions taken by the Connector are easy to identify and don’t appear to be done by an individual developer.

1. In Smartling, go to your GitHub Connector project
2. Click on the Settings tab > GitHub Settings > Add Set
   • The first time you click "Add Set" and then select “OAuth App” as the authentication mode, the Authorization wizard will open and prompt you to Authorize the Smartling GitHub Connector.
   • This is required to allow the OAuth App to work with your repositories.
3. Next, do one of the following:
   • If you own the organization in GitHub, you can authorize the Smartling GitHub Connector from the following wizard, as shown:
     
   • If you are not the owner of the organization in GitHub, you will first need to request approval from the organization's owners by clicking Request and Authorize from this wizard, as shown:
     

Authorization

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:

1. Go to your GitHub Settings > Applications > Authorized OAuth Apps
2. Select Smartling GitHub Connector and then select "request access"
3. 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

Tip: Once an owner has approved the request, the GitHub Connector will be able to access the organization, and the user will be able to see the organization and repository listed in the GitHub. 

 

STEP FOUR: Log into Your Smartling Account

Log into your Smartling account as an Account Owner or Project Manager user to complete the Connector configuration in Smartling.

STEP FIVE: Repository Setup

If you are setting up the Connector for the first time, complete the following steps to set up your repository for localization:

1. In Smartling, go to your GitHub Connector project.
2. Click on the Settings tab > GitHub Settings > Add Set.
3. Confirm that you would like to authenticate with OAuth App and click Next.
   
4. Choose the following from the drop-down fields:
   1. Select your Organization
   2. Select your Repository 
   3. Select the branch you want the GitHub Connector to monitor.
      The default is the main (master) branch, but for more information and guidance, read our documentation on Branch Strategy.
   4. Choose which mode you want to set the GitHub Connector to.
5. Click Next to set up a Configuration Set for the selected repository. 

Tip: For more information on the next steps, read our documentation on GitHub Connector Configuration Sets and Customizing GitHub Connector Configuration Sets.

Note: 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.

Adding a new repository 

If GitHub Apps are already set up for your Smartling account, you can add a new repository by simply creating a new Configuration Set:

1. In Smartling, go to your GitHub Connector project.
2. Click on the Settings tab > GitHub Settings.
3. In the GitHub Settings page, click Add Set.
4. Confirm that you want to authenticate with OAuth App and click Next.
   
5. Choose the following from the drop-down fields:
   1. Select your Organization
   2. Select your Repository 
   3. Select the branch you want the GitHub Connector to monitor.
      The default is the main (master) branch, but for more information and guidance, read our documentation on Branch Strategy.
   4. Choose which mode you want to set the GitHub Connector to.
6. Click Next to set up a Configuration Set for the selected repository.