[en] Remote Configuration

[en] :data-repo-content-url nil

[en] nil

[en] As described above, you can set almost all configuration values in a remote configuration file. The :data-repo-content-url configuration setting defines where to find the remote configuration. It can point to any subdirectory of a repository on GitHub.

[en] Note that it's not exactly the HTTPS URL you see in your browser, but rather the content URL as seen in the GitHub API. If your organization is called "org" and your repository "my-repo," and if you keep your configuration in a subdirectory "conf" in that repository, the URL would look like this:

[en] " https://api.github.com/repos/org/my-repo/contents/conf/{+path }"

[en] Keep the strange-looking +path part. In that remote folder, you can keep a file that needs to be named global-config.edn orglobal-config.json . You can use all supported configuration settings in this file. We recommend that you keep everything that's security related, like API tokens, in the local file.

[en] Note, that remote configuration settings are added to the local settings. That means you can't remove a configuration from the remote configuration file to "unset" it. To achieve that, you'll need to set it to nil.

[en] Logging to StatsD

[en] :statsd-host nil

[en] :statsd-port 8125

[en] nil

8125

[en] Enable sending metrics to a StatsD service. See Logging and Monitoring.

[en] Acrolinx for Azure DevOps Talking to GitHub (for the remote global configuration file)

[en] :gh-token "abc",

[en] :gh-token ["123" "345"]

[en] nil

[en] ENV and system properties for exactly one token. Vector format only in the configuration file.

[en] The GitHub User - Anonymous access to GitHub's APIs is limited. That's why you configure a token that the program uses to authenticate all calls to the GitHub API. The setting :gh-token can be a string (the token) or a vector of strings. You can define multiple tokens to avoid hitting the GitHub rate limit. The program uses the first token until it comes close to the rate limit, then the program switches to the next token. The tokens must belong to different GitHub accounts for this to work.

[en] The default makes Acrolinx for GitHub an unregistered user at GitHub. That won't work.

[en] :gh-secret (replacing the deprecated :secret configuration option)

[en] nil

[en] ENV and system property for single value

[en] Securing Requests - GitHub can sign the payload of requests with a shared secret. If you don't define secrets, nothing will be validated. An attacker could make you call their service and present your OAuth token (gh-token) to them! You can define one shared secret as a string or many as a vector. One of the many must validate. Fingerprinting is expensive at runtime as it must hash the complete body. The secret may also have umlauts like ä, ö, or other non-ascii characters. Make sure to save your EDN or JSON file in UTF-8 without byte-order-mark for that to work.

[en] :track-new-repos true

[en] false

[en] ENV and system property

[en] Automatically Register Repositories - If a :data-repo-content-url is configured, this program can collect all repositories it has seen in the repository registry during normal webhook operations. To enable this, you can set :track-new-repos to true.

[en] :event-queue-delay-ms (DEPRECATED – please remove from configuration files to use the default value)

[en] 100 (100 ms)

[en] ENV and system property

[en] Waiting for GitHub to Settle - Sometimes GitHub doesn't have our files ready for download even though we've received the webhook. According to their support, this is just how things are and we should wait a little. You can configure how long to delay each item. The delay takes the time already waited in the queue into account.

[en] Provide the Service

[en] :http-port 9779

9779

[en] ENV and system property

[en] HTTP - Acrolinx for GitHub opens an HTTP port which GitHub connects to.

[en] :user-db-file "/path/to/users.edn"

[en] undefined

[en] ENV and system property

[en] User Database - To authenticate users in the built-in dashboard, the configuration needs to have a user-database file. See Logging and Monitoring.

[en] The default is undefined, in which case this program tries to load the following files:

[en] If no files are found, the dashboard isn't available.

[en] :event-queue-size 1000

500

[en] ENV and system property

[en] Buffer Events - Acrolinx for GitHub allows event buffering from GitHub before it passes the documents to Acrolinx to check. It uses an in-memory queue for this. The queue schedules the requests of different GitHub users fairly. The GitHub event is received immediately and put on a channel. The items stored in the queue are just the incoming events in JSON form. They don't consume much memory. So, it's safe to make this queue quite large, for example 1000. Larger values usually hint that the Acrolinx Platform can't handle the load. If the queue is full, Acrolinx for GitHub drops new incoming events.

[en] :total-event-timeout-s

900

[en] (15 min)

[en] ENV and system property

[en] Limit Processing Time - When you submit a pull request, some files might bring unexpected complexity and take a long time for Acrolinx to process. Network connections can also be slow, and foreign APIs can show problems that consume too much time. To work around all of this and maintain service, you can configure a maximum processing time. You'll need to set this locally.

[en] You can also use this setting to stop processing pull request events that have reached the allowed time limit.

[en] Connect to Acrolinx

[en] :acrolinx-url "http://localhost:8031/"

[en] nil

[en] ENV and system property

[en] Acrolinx URL - The host and port of the Acrolinx Platform. Required. See Connect to Acrolinx.

[en] :acrolinx-auth-token "a very long string"

[en] nil

[en] ENV and system property

[en] Authenticating with a Token - Since Acrolinx Platform 5.2, the preferred authentication mechanism for embedded integrations is the API token. You can create one on the Acrolinx Dashboard in your user settings. Copy that string and paste it into the configuration in this key.

[en] :acrolinx-username "admin"

[en] :acrolinx-password "secret"

[en] nil

[en] ENV and system property

[en] Authentication with Username and Password - For backwards compatibility, Acrolinx for GitHub also supports authentication against Acrolinx via username and password. This will be removed in the future as it can compromise your user credentials and doesn't support Acrolinx setups with SSO or federated authentication.

[en] :acrolinx-parallel-threshold 5

5

[en] ENV and system property

[en] Faster Results with Parallel Checking - On systems with high load, you can configure Acrolinx for GitHub to submit several checks to Acrolinx in parallel. If the environment allows it, events with more relevant files than this threshold will split their workload on multiple threads. Larger numbers lead to more serial checking, smaller numbers to more parallel checking. Uses Java's ForkJoin framework under the hood.

[en] :acrolinx-parallel-workers

4

[en] ENV and system property

[en] Limit Parallel Requests - Acrolinx for GitHub lets you limit the number of parallel requests to the Acrolinx Platform. When you do this, the maximum number of parallel requests made to the Acrolinx Platform is based on the smallest of the following values: :acrolinx-parallel-workers or number of available threads.

[en] :guidance-profile "The UUID of your profile"

[en] nil

[en] Configure your Guidance Profile - You configure the Guidance Profile that you want to check with. You can configure all check settings in the Acrolinx Platform in the Checking Profile settings. You can find the UUID of the Guidance Profile in the Acrolinx Dashboard. See also Connect to Acrolinx.

[en] :metadata

[en] ENV and system property

[en] Map Metadata Names to Document Custom Field Names (currently a private beta) - Acrolinx for Git Hosting lets you use metadata values from the YAML front matter of a Markdown file to populate the corresponding document custom fields with that information. When you do this, you can use Target Batch Mapping in Markdown files. This is available at all configuration levels of the Git Hosting integration.

[en] The configuration option takes an EDN map for configuring EDN files and a JSON object for configuring JSON files. 

[en] If a metadata point named “foo” corresponds to a document custom field named “bar,” the :metadata configuration option would have the following structure:

[en] EDN configuration files

{:metadata {"foo" "bar"}}

[en] JSON configuration files

{":metadata": {"foo": "bar"}}

[en] file-size-limit

[en] nil

[en] ENV and system property

[en] Limit file size - Limit the size of the files that get processed for pull requests and baseline checks. This helps prevent out of memory issues.

[en] You'll want to set this in cases where a repository has files that are more than 1 MB. Specify this as :file-size-limit "Number Unit", where Unit can be B, kB, or MB. For example, :file-size-limit "1 MB".

[en] :filetypes

[en] Map a particular file format to the file extensions pertaining to that file format - This semantic grouping of file extensions instructs the Git Hosting integration to process files that match the file extensions specified in the :filetypes configuration option. It is important to note that “processing” on the integration’s end means sending a file to the Acrolinx Platform for it to be checked. Specifying this configuration option has no impact on how the content will be processed by the platform or if it will be checked at all.

[en] :ignored-filetypes

[en] :acrolinx-file-check-timeout

300

[en] (5 min)

[en] ENV and system property

[en] Set a Maximum Wait Time for a Check - For each check, you can configure a limit. Set a maximum wait time, and define useful polling intervals.

[en] This is set to 300 seconds (5 minutes) by default.

[en] Filter Checks

[en] Currently, Acrolinx for GitHub supports pull request events and push events. You can further filter what Acrolinx for GitHub checks with the options described in [en] Define What Acrolinx for Git Hosting Checks.

[en] Check Results

[en] :use-gh-statuses

[en] :use-gh-comments

[en] true

[en] ENV, system properties, global remote configuration, and repository-specific configuration

[en] Acrolinx for GitHub can create comments on GitHub and set the status of a commit. Acrolinx for GitHub creates comments on GitHub to show the results of an Acrolinx check.

[en] With statuses, you can use Acrolinx for GitHub as a quality Gateway. For this, you use the setting :targets to define your target criteria. This setting only works in the configuration files (local, remote, repo-specific). ENV and system properties aren't supported.

[en] For detailed information, see Check Results.

[en] :gh-status-when-no-check