Skip to main content
 

How can we help?

Search

Install Acrolinx for Azure DevOps (ADO) Git

  • Updated

Before you install this version of Acrolinx, make sure that you already have the following:

GitHub and ADO Git

GitHub and ADO Git Versions

Acrolinx for GitHub and ADO Git Versions

Notes

Supported

Maintained

Deprecated

Support for Acrolinx AI Assistant and Suggestions

Latest versions of GitHub and ADO Git

4.2.6

4.2.5

4.2.4 and earlier

--

JRE 11 or later is required for Acrolinx for GitHub and ADO Git versions 4.2.3 and later.

If you want to know whether this version of Acrolinx for ADO Git is compatible with your local platforms, check our Compatibility Guide.

Acrolinx system requirements

For the webhook server installation, make sure that your host system has the following:

  • JRE 8 (Oracle or OpenJDK)

    Note

    For Acrolinx for Git Hosting versions 4.2.3 and later, JRE 11 or later is required.

  • We recommend 1 GB of RAM.

    Note

    Very large documents or a very large internal event queue might require more memory.

Install

To get started, choose a computer to host Acrolinx that's accessible from the Azure DevOps Cloud. We assume a POSIX-like operating system.

Generate an access token in Azure DevOps

  1. Select a Azure DevOps service account to use for this integration and select User settings User settings icon from top-right of Azure DevOps window in the top right.

  2. Go to Personal access tokens in the dropdown and click New Token.

  3. Name your token, select the organization where you want to use the token, and then set your token to expire automatically after a set number of days.

    The current needed scope for your token includes:

    • Code: read and status.

    • Pull request threads: Read and write.

    For security reasons, it's best not to extend this scope.

    Click Create and copy the token.

Generate an access token in GitHub

  1. In GitHub, select a service account to use for this integration (you’ll need it for the remote global configuration) and go to Settings > Developer settings.

  2. Click Personal access tokens > Generate new token. Give it a clear description and select all permissions in the repo scope. Limit the token to the repository that hosts the remote global configuration.

  3. Click Generate token, and copy your new token.

Start the service

  1. On the new computer, create a dedicated operating system user for Acrolinx, for example "acrolinx."

  2. Create the file /home/acrolinx/.config/Acrolinx/githubhook/acrolinx-githubhook.edn or /home/acrolinx/.config/Acrolinx/githubhook/acrolinx-githubhook.json and all the directories in its path.

    • For Azure DevOps:

      • Add your token as :ado-token

      • Create a (complicated) shared secret and add it as :ado-secret.

    • For GitHub:

      • Add your token as :gh-token

    • Configure access to your instance of Acrolinx by adding :acrolinx-url and :acrolinx-auth-token (an API token from Acrolinx).

    • Configure your Guidance Profile using :guidance-profile. For more information, see Connect to Acrolinx

      Tip

      Before you configure your Guidance Profile, you can test the connection to Acrolinx and pull information from it with the --acrolinx-capabilities command. This confirms that your personal access token has the right configuration. It also verifies that the token owner has the right permissions (the role “author”).

  3. Create a log configuration file with debug settings. You can create a sample file for the log configuration by running Acrolinx with the --sample-log command-line option. For more details, see our article on logging and monitoring.

  4. Start Acrolinx for GitHub.

Install a webhook

You need to configure a webhook for each repository that you’ll use with Acrolinx. You can also configure a webhook with access to all repositories the service account can access.

Configure the service hook notifications

To create your service hook notifications, do the following:

  1. Go to Project settings > Service hooks > Create subscription. Select the Web Hooks service and click Next.

  2. Select Pull request created under Trigger on this type of event on the Trigger page.

    • Optional: restrict the Service Hook Subscription to a single repository.

    • Optional: restrict the Target Branch. If you issue each pull request to be merged on a single target branch, enter the name of the branch here.

    Click Next.

  3. On the Action page:

    • Set URL to the URL of the Azure DevOps integration webhook. This URL must end with /listen. The use of TLS (https protocol) to connect with the webhook is mandatory to protect the Azure DevOps secret.

    • Set Basic authentication username to the word secret.

    • Enter the Azure DevOps secret as the password for this user in the Basic authentication password field.

    • Set Resource details to send to All.

    • Set Messages to send and Detailed messages to send to None.

  4. Click Finish.

  5. Go to Project settings > Service hooks > Create subscription. Select the Web Hooks service and click Next.

  6. Select Pull request updated and repeat steps 3 and 4.

To test the webhook configuration, you'll need to create or update a pull request.

Integrate in Systemd

If you want Acrolinx to start at boot time and restart after a crash, you can use a service description for systemd. You'll do this by extracting acrolinx-githubhook.service from the JAR file. For example: jar xf githubhook-1.7.0.jar acrolinx-githubhook.service.

  1. On a production system, copy the service file to /etc/systemd/system and edit the path to point to the correct JAR and user.

  2. Call systemctl enable acrolinx-githubhook to enable starting at boot.

  3. Call systemctl start/stop acrolinx-githubhook to start/stop the service.

This only applies to Linux systems that use systemd (as opposed to Upstart or SysVinit).

Command line options

For a description of the available command-line options, display help on the command line:

java -jar githubhook-[versionnumber].jar --help