[en] Acrolinx for GitHub reads its configuration from the following sources:
-
[en] A user-specific, local config file:
-
[en] Path to file given with --config command-line option
-
[en] Path to file found in
ACROLINX_GITHUBHOOK_CONFIGURATION
environment variable -
[en] Default
~/.config/Acrolinx/githubhook/acrolinx-githubhook.edn
OR~/.config/Acrolinx/githubhook/acrolinx-githubhook.json
-
-
[en] Environment variables
-
[en] System properties given at the command line.
-
[en] A remote file in a GitHub repository, given by the
:data-repo-content-url
configuration. This is called the global remote configuration file. -
[en] 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.
Tipp
[en] 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.
[en] This program uses the environ library and merges that into everything found in the config file. That yields the following order of settings:
-
[en] Repository-specific configuration file for selected settings. Read more about them in Repository-specific configurations
-
[en] Remote configuration file
-
[en] Java system properties (-D switch on the command line)
-
[en] Environment variables
-
[en] User-specific configuration file
Wichtig
[en] 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.
[en] Naming conventions for settings are:
-
[en] Environment variables are all uppercase and separated by an underscore.
-
[en] Properties are lowercase and separated by a dot.
-
[en] Configuration file has an EDN map or JSON object with kebab-case keys.
Beispiel 1. [en] Configure the size of the unprocessed events queue
[en] For example, the configuration for the unprocessed events queue would look as follows:
[en] In your $HOME/.bashrc
export EVENT_QUEUE_SIZE=50
[en] or on the command line
java -Devent.queue.size=50 -jar githubhook.jar
[en] or in the user configuration file
{:event-queue-size 50}
[en] You can generate a sample configuration by running Acrolinx for GitHub with the --sample-config
command-line switch.
[en] 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.
[en] 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:
-
[en]
:template-header
-
[en]
:template-change
-
[en]
:template-footer
-
[en]
:allowed-event-types
-
[en]
:ignored-senders
-
[en]
:allowed-filename-matches
-
[en]
:allowed-branchname-matches
-
[en]
:allow-merges-from-default
-
[en]
:use-skip-label
-
[en]
:use-gh-statuses
-
[en]
:use-gh-comments
-
[en]
:gh-status-skip-errors
-
[en]
:gh-status-when-no-check
-
[en]
:guidance-profile
-
[en]
:acrolinx-client-locale
-
[en]
:acrolinx-author-field
-
[en]
:targets
-
[en]
:changed-files-limit
-
[en]
:file-size-limit
[en] 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 [en] Format Migration for Configuration Files and Repository Registry.
[en] 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.
[en] 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.
[en] 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
.