Instructions for setting up the Acrolinx integration for GitHub on a repo

Acrolinx is an editorial and voice feedback solution available for prioritized APEX technical content sets. It helps provide baseline quality feedback to authors and it helps drive CSAT through basic quality. Because it is a third-party product, there is cost associated with using Acrolinx.

The APEX content publishing business determines, based on business priorities, where Acrolinx will be enabled. Please talk to tysonn if you have questions. You cannot enable Acrolinx in a repo without business approval from tysonn and carolz.

How does it work?

The Acrolinx integration for GitHub relies on multiple things to work:

  • The Acrolinx server, which is running on a Linux virtual machine in Azure. This is hosted and run by Acrolinx and their vendor hosting company.
  • An Acrolinx configuration file in the root directory of the repo you want to monitor.
  • The integration relies on four GitHub accounts that are tied to four Microsoft service accounts, all of which have 2FA enabled. These accounts are grouped together in a GitHub team. A repo admin must give the team Write permissions in the monitored repository.
  • A configured web hook in the repo that is activated by Push and Pull Request events.

List of GitHub accounts

This is the list of service and GitHub accounts that the service relies on. Passwords and tokens are maintained by tysonn.

MSFT Service Account GitHub service account
acrolnx1@microsoft.com acrolinxatmsft1
acrolnx2@microsoft.com acrolinx-at-msft2
acrolnx3@microsoft.com acrolinx-at-msft3
acrolnx4@microsoft.com acrolinx-at-msft4

These accounts belong to the acrolinx-service-accounts team in the following organizations:

  • MicrosoftDocs
  • Azure
  • Microsoft

Prerequisites

  • You have to have permission from the business SME to enable a new repository, this is controlled by a secret you must obtain to turn the webhook on.
  • Understand: the four Acrolinx service accounts each have a GitHub account. Each of these GitHub accounts has 2FA enabled. The GitHub integration relies directly on these service accounts and on their GitHub access tokens.
  • You must add the four Acrolinx service accounts to your instance of Outlook so you can receive and act on email notifications sent to the service account by GitHub. You’ll need the corpnet passwords to these accounts as well.
  • You must have access to the 2FA iPhone owned by the organization so you can log into the GitHub accounts that correspond to the Acrolinx service accounts.

Part 1: Give the Acrolinx service accounts access to the repository

In the repo in which you want to activate Acrolinx, a person with Admin perms must go to Settings>Collaborators & team. In the Teams section, type the name of the team that includes all the Acrolinx service accounts and then select acrolinx-service-accounts. Set the permission level to Write for the team.

  1. In the default branch of the repository, add a new file called .acrolinx-config.edn to the root of the repository.

  2. Copy the content of the file from an existing monitored repository.

  3. Specify the branches that you want to monitor – at a minimum, you need to monitor your default branch, which is probably master. We recommend standard naming conventions for release branches be used so that Acrolinx will run automatically in release branches without configuration changes. The following setting ensure that Acrolinx always runs in master, and in any branch whose name starts with release or sandbox.

    {:allowed-branchname-matches ["master" "release-.*" "sandbox-.*"]
    :allowed-filename-matches ["articles" "includes"]}
    
  4. Specify the folders in the root that you want Acrolinx to monitor. You only want to monitor root folders that contain conceptual or overwrite content. Don’t monitor folders that contain autogenerated content.

    {:allowed-branchname-matches ["master" "release-.*" "sandbox-.*"]
    :allowed-filename-matches ["articles" "includes"]}
    
  5. Make no other changes to the template. The Acrolinx template is managed by tysonn and should remain standard across all repositories.

  6. Save, add, and commit the changes, and create a pull request to the default branch to add the config file to the repo.

Part 3: Enable the web hook

  1. Ensure you are logged into GitHub with an account that has Admin perms.
  2. In the repository you want to monitor, click Settings>Webhooks>Add webhook
  3. Configure the web hook as follows:

    • Payload URL: https://microsoft-ce-csi.acrolinx.cloud/githubhook/listen/ (include the closing slash)
    • Content type: application/json
    • Secret: Enter the secret.
    • In the “Which events would you like to trigger this webhook?” section, select “Let me select individual events”.
    • Select Pull request, select Push, and then select Active.
    • Click Add webhook.

Part 4: Test the implementation

Create a test pull request on an article in the repository. The Acrolinx integration should write a comment to the pull request thread within 5 minutes or less.

Troubleshooting

If the test fails, you should:

  • Verify that you gave the Acrolinx GitHub accounts write permissions in the repo.
  • Verify the config file was merged to the default branch.
  • Verify you spelled the branch names and root folders correctly in the config file.
  • Verify the webhook setup.

Monitoring

You can monitor which repositories are active and what is going on with them from the Acrolinx for GitHub Dashboard: https://microsoft-ce-csi.acrolinx.cloud/githubhook/status/app (User name and password required)