Skip to main content
 

How can we help?

Search

Install, Uninstall, or Update Acrolinx for GitHub

  • Updated

Before you install this version of Acrolinx for GitHub, 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.

Check our Compatibility Guide if you want to know whether this version of Acrolinx for GitHub works with your local platforms.

Install

To install Acrolinx for GitHub, follow these steps:

  1. Prepare a computer to host Acrolinx for GitHub that can be reached from your GitHub instance (cloud or on-premise). We assume a POSIX-like operating system.

  2. Select a GitHub account to use for this integration and visit the settings page.

    1. Select Developer settings.

    2. Go to Personal Access Tokens.

    3. Create a new token. Give it a clear description and tick all permissions in the repo scope.

    4. Download the token.

  3. If it is your account, you must have write access to each repository where you’ll use this integration.

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

  5. 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.

  6. Add your token as :gh-token. Learn how Acrolinx works with fine-grained personal access tokens.

  7. Create a (complicated) shared secret and add it as :gh-secret.

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

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

    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 the personal access token is configured correctly. It also verifies that the owner of the token has the necessary rights (the role “author”) on the Acrolinx Platform.

  10. Create a log configuration file with debug settings. See the "Logging" section. You can create a sample file for the log configuration by running Acrolinx for GitHub with the --sample-log command-line option.

  11. Start Acrolinx for GitHub.

Webhook installation

As a GitHub administrator, you need to configure a webhook for each repository that you’ll use with Acrolinx for GitHub. You can either automate this or do it manually.

Acrolinx system requirements

The minimum requirement for the webhook server installation is a computer with the following features:

  • 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. Very large documents or a very large internal event queue might require more memory.

Automated

  1. Create an installation file. The installation file has to be in the EDN format and needs to have a hash map with the following keys:

    :gh-admin-token: A GitHub API token with admin permissions for each repository the webhook will be added to.

    :api-base-url: The base URL of the GitHub API. For http://github.com this is "https://api.github.com/" but it will differ for an on-premise installation of GitHub.

    :hook-url: The URL that addresses Acrolinx for GitHub.

    :gh-secret: The shared secret. This is sensitive data. Make sure to protect it well.

    :repos: A nested hashmap that has the repository coordinates as keys and the desired events as values.

    Call this program on the command line using the --sample-install option to create a sample installation file.

  2. Run this program from the command line with the option --install-hook and provide the installation file as the argument.

    java -jar githubhook.jar --install-hook install-admin.edn

Manual

If you prefer to configure the webhooks manually, the steps are as follows:

  1. Visit the settings page of your repository and add a webhook.

  2. Point the Payload URL to your computer (if applicable) using the correct port, for example: http://yourmachine.example:9779/listen/

  3. Tick Let me select individual events and select Pull request and/or Push, depending on your use case. Note that you can configure Acrolinx for GitHub to only accept certain events by specifying :allowed-event-types in the configuration.

  4. Add your shared secret.

When you save the webhook configuration, a PING event is delivered to Acrolinx for GitHub. You can debug problems in GitHub in the Recent deliveries section of the webhook configuration page. On the receiving end, look at the (debug) logging of this program.

Integrate in Systemd

To enable Acrolinx for GitHub to start at boot time and restart after a crash, a service description for systemd is available: extract acrolinx-githubhook.service from the JAR-file (for example, jar xf githubhook-1.7.0.jar acrolinx-githubhook.service).

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

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

  • 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 command-line options that you can use, display help on the command line:

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

Uninstall

To uninstall Acrolinx for GitHub, you need to update the webhook that is connected to Acrolinx. Follow the instructions in Managing global webhooks in the GitHub Docs.