Setting up the GitHub Connector with GitHub App

This is the recommended authentication type when setting up the GitHub Connector. For more information, see our documentation on Types of Authentication for the GitHub Connector.

Info: This article explains how to set up the GitHub Connector and is intended for Smartling Account Owners, Project Managers, and GitHub organization members.

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 

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

STEP TWO: Install Smartling’s GitHub App

Install Smartling’s GitHub App using the installation link provided here. A user with GitHub Organization Admin rights must do this, as GitHub Apps are installed at the organizational level.

The App needs to be installed only once. All permissions used by the App are listed on the installation page. If a future functionality update requires updated permissions, you will be alerted via GitHub to review and approve the modifications.

To ensure the correct functioning of the Connector, please grant Smartling’s GitHub App access to all repositories relevant to the localization process.

From your GitHub organization, navigate to Third-party Access > GitHub Apps.
Once there, you can review Smartling’s GitHub App and manage the repositories that it has access to.

STEP THREE: Authorize connection to Smartling’s GitHub App

You must now authorize your Smartling platform account to connect with the Smartling GitHub App installed in your organization(s). Once an authorization is in place, the GitHub App can work safely with your organization and repositories.  

To authorize the Smartling platform to connect to your GitHub App installation, you must log in to GitHub while creating the authorization. The logged-in user's credentials will not be saved or reused; they are only required once to connect your Smartling account to your GitHub organization(s).

1. In your Smartling account, go to Account Settings > Integrations > GitHub.
2. Click Add Authorization.
   
   
   
3. You will be prompted to log into GitHub when authorizing the connection between Smartling and GitHub.
   This safety precaution ensures that only someone with access to your GitHub organization can authorize a connection from your Smartling account. The user authorizing the does not require organization admin rights; they only need access to the organization. 

4. You can now select all organizations you want to connect with your Smartling account. 
5. If Smartling’s GitHub App has not been installed for your organization yet, you must first click the link to install the app In GitHub.
   
   Once installed, go back to the Smartling page and click Refresh.
   You can now select any organizations for which the GitHub App has been installed.
   
6. Click Save to confirm the Connector authorization. 
7. The authorization will be enabled by default.

Once the authorization is in place, Smartling will use the GitHub App permissions and access to execute its normal functions, and no service user will be involved. 

Disabling or deleting an authorization

If a specific authorization is no longer required, it can be disabled or removed permanently by selecting the Delete option from the ellipses menu:

1. Before disabling and deleting, ensure any translation jobs triggered by Configuration Sets using this authorization are completed and delivered to GitHub.
2. After all translation jobs are completed, disable any Configuration Sets using that authorization.
3. Then, you can safely disable or delete the authorization. 

STEP FOUR: Create Configuration Sets

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 GitHub Apps 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 most common choice is the main 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 installed and authorized 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 GitHub Apps 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 most common choice is the main 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.