Skip to main content
 

How can we help?

Search

Configurations Explained

  • Updated

Acrolinx for GitHub reads its configuration from the following sources:

  • A user-specific, local config file:

    • Path to file given with --config command-line option

    • Path to file found in ACROLINX_GITHUBHOOK_CONFIGURATION environment variable

    • Default ~/.config/Acrolinx/githubhook/acrolinx-githubhook.edn OR ~/.config/Acrolinx/githubhook/acrolinx-githubhook.json

  • Environment variables

  • System properties given at the command line.

  • A remote file in a GitHub repository, given by the :data-repo-content-url configuration. This is called the global remote configuration file.

  • When processing an event, another remote configuration file from the repository that triggered the event is read for a selected set of settings. This is called the repository-specific configuration file.

Tip

We recommend using the user-specific configuration file or environment variables for sensitive settings like access tokens and the Acrolinx URL. Manage all other settings in the remote configuration file.

How configurations are applied

This program uses the environ library and merges that into everything found in the config file. That yields the following order of settings:

  • Repository-specific configuration file for selected settings. Read more about them in Repository-specific configurations

  • Remote configuration file

  • Java system properties (-D switch on the command line)

  • Environment variables

  • User-specific configuration file

Important

You can always dump the computed configuration with the --dump-config command-line option. This includes the remote configuration. Not all configuration settings support all sources. The settings that are maps and vectors in particular only work in the configuration files.

Naming conventions

Naming conventions for settings are:

  • Environment variables are all uppercase and separated by an underscore.

  • Properties are lowercase and separated by a dot.

  • Configuration file has an EDN map or JSON object with kebab-case keys.

Example 1. Configure the size of the unprocessed events queue

For example, the configuration for the unprocessed events queue would look as follows:

In your $HOME/.bashrc

export EVENT_QUEUE_SIZE=50

or on the command line

java -Devent.queue.size=50 -jar githubhook.jar

or in the user configuration file

{:event-queue-size 50}

Generate a sample configuration

You can generate a sample configuration by running Acrolinx for GitHub with the --sample-config command-line switch.

The sample configuration includes a list of all supported configuration settings that you can use as the user-specific configuration file. These are already in the EDN or JSON format.

Repository-specific configurations

You can set every configuration once for your installation of this program. Do this in either the local file or in the remote configuration. But sometimes you may want to overwrite settings in the GitHub repositories on a per-repository basis. You can set the following configuration keys in the GitHub repository that sent the GitHub event:

  • :template-header

  • :template-change

  • :template-footer

  • :allowed-event-types

  • :ignored-senders

  • :allowed-filename-matches

  • :allowed-branchname-matches

  • :allow-merges-from-default

  • :use-skip-label

  • :use-gh-statuses

  • :use-gh-comments

  • :gh-status-skip-errors

  • :gh-status-when-no-check

  • :guidance-profile

  • :acrolinx-client-locale

  • :acrolinx-author-field

  • :targets

  • :changed-files-limit

  • :file-size-limit

To configure these values in a repository, create a file called .acrolinx-config.edn or .acrolinx-config.json in the root of your repository. This file needs a valid EDN hash map or JSON object with only the keys listed above. If this file has any errors, Acrolinx ignores the settings. If you need to validate your changes to configuration files, you can do this with JSON and the Web IDE of the Git Hosting platform. Read more in Format Migration for Configuration Files and Repository Registry.

Errors are written to the log file. To avoid extra calls that count against the GitHub rate limit, files are cached in the program. Files are checked for changes for every GitHub event that's being processed.

As a rule, the settings in the repo configuration override the global settings on the server side. That's why the repo settings are limited to a fixed set of supported keys. An exception to the rule is the value of :acrolinx-check-settings, which gets merged. This is only relevant for the legacy Acrolinx API.

Note, that repo configuration settings are added to all other settings. That means you can't remove a configuration from the specific configuration file to "unset" it. To achieve that, you'll need to set it to nil.