:data-repo-content-url nil

nil

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.

The URL used isn't exactly the HTTPS URL that you see in your browser. Instead, it's the content URL as seen in the GitHub API. If your organization is called "org," your repository "my-repo," and you store your configuration in a subdirectory called "conf" in that repository, the URL would look like this:

ttps://api.github.com/repos/org/my-repo/contents/conf/{+path }

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.

You can't simply remove a configuration from the remote configuration file to "unset" it. To remove a setting, set it to nil.

:track-new-repos true

false

ENV and system property

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.

:statsd-host nil

:statsd-port 8125

nil

8125

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

:gh-token "abc",

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

nil

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

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.

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

:gh-secret (replacing the deprecated :secret configuration option)

nil

ENV and system property for single value

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.

:http-port 9779

9779

ENV and system property

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

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

undefined

ENV and system property

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

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

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

:event-queue-size 1000

500

ENV and system property

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 Acrolinx can't handle the load. If the queue is full, Acrolinx for GitHub drops new incoming events.

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

100 (100 ms)

ENV and system property

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.

:total-event-timeout-s

900

(15 min)

ENV and system property

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 could also be slow, and foreign APIs might 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.

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

:acrolinx-url "http://localhost:8031/"

nil

ENV and system property

Acrolinx URL - The host and port of Acrolinx. Required. See Connect to Acrolinx.

:acrolinx-auth-token "a very long string"

nil

ENV and system property

Authenticating with a token - You can create one in the Users section when you sign in to Acrolinx. Copy that string and paste it into the configuration in this key.

:acrolinx-username "admin"

:acrolinx-password "secret"

nil

ENV and system property

Authentication with username and password - For backwards compatibility, Acrolinx for GitHub also supports authentication against Acrolinx via username and password. We’ll remove this in the future as it can compromise your user credentials and doesn't support Acrolinx setups with SSO or federated authentication.

:acrolinx-parallel-threshold 5

5

ENV and system property

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.

:acrolinx-parallel-workers

4

ENV and system property

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

:metadata

ENV and system property

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.

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

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

EDN configuration files

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

JSON configuration files

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

file-size-limit

nil

ENV and system property

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.

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

:filetypes

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’s important to note that “processing” on the integration’s end means sending a file to Acrolinx for checking. When you specify this configuration option, it has no impact on how Acrolinx processes the content or if it's checked at all.

See Supported Input Types for more information on the supported file types.

These are the base values for :filetypes:

{"XML"
   #{"xml" "xhtm" "xhtml" "svg" "resx" "xlf" "xliff" "dita" "ditamap"
     "ditaval"}

   "HTML"
   #{"html" "htm"}

   "MARKDOWN"
   #{"markdown" "mdown" "mkdn" "mkd" "md"}

   "TEXT"
   #{"txt"}

   "JAVA"
   #{"java"}

   "CPP"
   #{"c" "h"
     "cc" "cpp" "cxx" "c++"
     "hh" "hpp" "hxx" "h++"
     "dic"}

   "YAML"
   #{"yaml" "yml"}

   "PROPERTIES"
   #{"properties"}

   "JSON"
   #{"json"}

   "PDF"
   #{"pdf"}

   "MS_OFFICE"
   #{"docx" "docm" "pptx" "pptm" "xlsx" "xlsm" "vsdx"}
   }

If you would like Acrolinx to process a novel file format, you would need to specify it as follows:

EDN
{:filetypes 
  {"NEW_FILE_FORMAT"
   #{"foo", "bar"}}}

JSON
{
    ":filetypes": {
        "NEW_FILE_FORMAT": [
       "foo", "bar"
        ]
    }
}

:ignored-filetypes

Ignore the file extensions pertaining to a specific format - Instruct the Git Hosting integration to ignore files that match the file extensions specified.

:acrolinx-file-check-timeout

300

(5 min)

ENV and system property

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.

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

:use-gh-statuses

:use-gh-comments

true

ENV, system properties, global remote configuration, and repository-specific configuration

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.

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.

For detailed information, see Check Results.

:gh-status-when-no-check

false

ENV, system properties, global remote configuration, and repository-specific configuration

When Acrolinx for GitHub and ADO Git doesn’t check any files in a pull request, it doesn’t automatically update the status of the pull request. You can adjust this if you prefer to receive pull request status updates regardless.

When you set :gh-status-when-no-check to true, the status for the pull request will be marked as “passing” and the status description will be “Acrolinx checked no files.”