Back to top image

Setting Up Your GitHub Connector

This article is for Smartling Account Owners and Project Managers users and GitHub Organization member/Repository Admin users on how to set up the GitHub Connector.

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.

STEP TWO: Set Up Your Team

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 role for the GitHub Connector, which is not used for any other activities within your repository, such as smartling@your_business_email.com. This prevents disruptions to your integration if the original user account becomes deactivated for any reason. This also ensures that any action taken on behalf of the Smartling connector can be easily identified.

The GitHub Connector relies on users being a GitHub organization owner or member and having admin access to the repository.

The reason why your GitHub localization team must all have Admin user access to the repository, is because we require GitHub's Change a Repository's Settings permission to add and remove our webhooks. This is required to modify the Connector configuration set.

Tip: For steps on how to change the authenticated GitHub user, read our documentation on Changing Authentication Users on The GitHub Connector.

Smartling User

The Smartling user must be an Account Owner or Project Manager user.

Tip: To summarize, the dedicated email address must be a GitHub Organization owner/member, a repository admin, and a Smartling Account Owner/Project Manager, and logged into one GitHub Organization when setting up/modifying the connector configuration.

How To Create a GitHub Member

  1. Follow 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.
    GitHub-AddRepoMakeAdmin.png

STEP THREE: Authorize Smartling in GitHub

2FA works with the connector and is used during this 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, won't require 2FA. 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" will open the Authorization wizard for you to Authorize the Smartling GitHub Connector.
    • This is required to allow Smartling to monitor your repository.
  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:
      Screenshot_2020-12-17_at_11.20.35.png
    • 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:
      request.png

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 Connector settings page in Smartling.

STEP FOUR: Repository Setup

If you're setting up the connector for the first time, complete the following steps to set up your repository:

  1. Choose the following from the dropdown fields:
    • Select your Organization
    • Select your Repository
    • 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
    • Choose which mode you want to set the GitHub Connector to.
  2. Click Next to set up a configuration set for the repository.

If the connector is already set up, and you wish to add a new repository to the integration, complete the following steps:

  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 and choose the following from the dropdown fields:
    • Select your Organization
    • Select your Repository
    • 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
    • Choose which mode you want to set the GitHub Connector to.
  4. Click Next to set up a configuration set for the repository.

Table of Contents