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, you can follow the steps in How to Create a Project. Ensure that all languages, workflows, team members, and linguistic assets are correctly set up.
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.
You will see a summary of the permissions used by the Smartling GitHub App, and you will be able to grant access to either all your repositories or only specifically chosen ones.
When restricting access to a specific set of repositories, you will need to update this in your GitHub organization whenever a new repository is added to the localization process.
STEP THREE: Authorize connection to Smartling’s GitHub App
You'll now need to 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.
Only Account Owners can create new authorizations and modify existing authorizations. Project Managers have view-only access.
To authorize the Smartling platform to connect to your GitHub App installation, you must log in to GitHub during the authorization process. The logged-in user's credentials will not be saved or reused; they are only required one time to connect your Smartling account to your GitHub organization(s).
- In your Smartling account, go to Account Settings > Integrations & Developer Tools > GitHub.
- Click Add Authorization.
- 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.
- You can now select all organizations you want to connect with your Smartling account.
- 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.
- Click Save to confirm the Connector authorization.
- 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:
- Before disabling and deleting, ensure any translation jobs triggered by Configuration Sets using this authorization are completed and delivered to GitHub.
- After all translation jobs are completed, disable any Configuration Sets using that authorization.
- Then, you can safely disable or delete the authorization.
You will be prompted with a confirmation message both when disabling and deleting an authorization.
STEP FOUR: Create Configuration Sets
- In Smartling, go to your GitHub Connector project.
- Click on the Settings tab > GitHub Settings > Add Set.
- Confirm that you would like to authenticate with GitHub Apps and click Next
- Choose the following from the drop-down fields:
- Select your Organization
- Select your Repository
- 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.
- Choose which mode you want to set the GitHub Connector to.
- 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.
Connecting to a new repository
If the Smartling GitHub App is already installed and authorized for your Smartling account, you can add a new repository by simply creating a new Configuration Set:
Remember: update the selected list if you aren't allowing the GitHub App to access all repositories in your organization.