Configuration

Quick Start
Workflow Parameters
Files
See Configuration: Workflows for the general workflow modes

Workflow Parameters

See Configuration: Workflows for the supported GitHub workflows.

Parameter	Description
GITHUB_TOKEN	github credential secret for api requests
config	directory with config files
dictionary_url	url for primary dictionary
dictionary_version	version of primary dictionary
experimental_apply_changes_via_bot	allow @check-spelling-bot to update PRs
experimental_parallel_jobs	parallelize spell checking file tasks
shortest_word	minimum word length
longest_word	maximum word length
post_comment	post comment
experimental_path	Directory root to check for spelling (note that bucket/project/config are independent of this)
capture_output_unknown_words	Capture unknown words (should be added to expect.txt) as an action output
capture_output_stale_words	Capture stale words (should be removed from expect.txt) as an action output
capture_output_skipped_files	Capture skipped files (could be added to excludes.txt) as an action output
experimental_commit_note	If set, commit updates to expect automatically with this note
only_check_changed_files	If set, only check changed files
dictionary_source_prefixes	prefixes for urls for dictionaries defined in extra_dictionaries
extra_dictionaries	Dictionaries to include
check_extra_dictionaries	If there are unknown words, see if they are in these additional dictionaries
extra_dictionary_limit	The number of check_extra_dictionaries to report
event_aliases	Map an unsupported GitHub event to a known event
suppress_push_for_open_pull_request	If running from a `push` event and there's an open `pull_request`, stop working and rely on the `pull_request` handling to check the branch
report_title_suffix	Appended to title (for use in matrix configurations)
warnings	Treat specific errors as warnings
notices	Treat specific errors as notices
custom_task	Workflow magic
internal_state_directory	Workflow magic
check_file_names	Spell check file paths
anonymize_secpoll_source	Use public dns to check action security state
ignore_security_advisory	Override action security state warning
largest_file	Ignore large files
unknown_word_limit	Limit the number of reports per unknown word
disable_checks	Disable various check-spelling behaviors
check_commit_messages	Check commit / PR metadata
use_magic_file	Detect binary files
use_sarif	Generate SARIF Reports
summary_table	Summary Table
report-timing	Report file processing times
alternate_engine	Use another version of check-spelling
alternate_engine_key	ssh key to check out alternate version of check-spelling
cache-dictionaries	Allows workflows to disable caching dictionaries
caller_container	Hack for `act`
candidate_example_limit	Limit the number of reports per pattern suggestion
checkout	Let action manage checkout process
ignore-pattern	Characters to ignore while parsing lines
lower-pattern	Pattern describing lowercase characters while parsing lines
not-lower-pattern	Pattern describing non-lowercase characters while parsing lines
not-upper-or-lower-pattern	Pattern describing characters that are neither uppercase nor lowercase while parsing lines
punctuation-pattern	Pattern describing punctuation characters while parsing lines
upper-pattern	Pattern describing uppercase characters while parsing lines
quit_without_error	Cause action not to trigger a failure state regardless of its internal status
spell_check_this	Fallback configuration data to use with checkout
ssh_key	Git ssh key for checking out (to enable writes with workflows)
task	Workflow magic

See Configuration: Advanced for additional options.

GITHUB_TOKEN

Specify the token to be used when making API calls to GitHub. By default the GITHUB_TOKEN is used.

⚠️ @dependabot appears to be unfriendly to this token.

Note: GitHub Actions get an automatic token which allows for read operations. If the Action is a pull_request and the originating repository isn't trusted, then the automatic token will not have write permission, which means it won't be able to post a comment to the PR, there are three ways to address this:

Use pull_request_target recommended as of 0.0.17-alpha

Create a custom Personal Access Token with repo read + comment

Use schedule instead

config

Default: .github/actions/spelling

In this directory, you can place files to influence the spell checker.

dictionary_url

If you don't define a dictionary using dictionary files, the spell checker will retrieve a dictionary. You can provide a different url if you have a preferred base. The default includes a variable ($DICTIONARY_VERSION) for a version.

This feature is new with 0.0.17.

dictionary_version

If dictionary_url includes ($DICTIONARY_VERSION), you can override the default version.

Over time, the default version will probably change. See versioned dictionaries for more information.

experimental_apply_changes_via_bot

Allow @check-spelling-bot to update PRs by incorporating the feedback it reports.

ℹ️ Af of v0.0.21, this feature might be ready for use.

If everyone in a repository is a member, or if PRs from externals are unlikely to receive comments from externals besides the PR author, and you don't have other bots that would write comments on PRs, then you could use it.
To prevent it from 💬 in response to other bot's comments or other accounts not associated with the PR explaining that it's confused, it should have a condition like this:

```yaml
  if: ${{
    github.event_name == 'issue_comment' &&
    github.event.issue.pull_request &&
    contains(github.event.comment.body, '@check-spelling-bot apply')
    }}
```

See https://github.com/check-spelling/spell-check-this/blob/3a35a1cec1e660ab04638cbd5bdd086cf2fcd5c5/.github/workflows/spelling.yml#L126

Current recommended practice is to only enable this feature in private repositories or forks, but not public upstreams.

The code is designed to refuse to operate in response to anyone who doesn't have write access to the repository.

experimental_parallel_jobs

The number of concurrent spell checking tasks to run.

GitHub Linux/Windows VMs have 2 cores and thus the default is 2. GitHub's macOS VMs have 3 cores.

If you run your own VMs with more cores, you could use a higher number.

shortest_word

The minimum word length to consider. The default is 3 (previously it was 2). Note that this will autotune to no shorter than the shortest word in the dictionary.

longest_word

The longest word length to consider. The default is two characters longer than the longest word in the dictionary. Previously strings that were thousands of characters long were flagged.

post_comment

If you want to suppress commenting, you can use this.

Note: if you're using a split workflow, you will use this in the main task stage, and will not use it in the comment stage.

experimental_path

If you want to specify the directory to test, and so to not test all the project files. Default is ..

capture_output_unknown_words

Capture unknown words as an action output so it can be used in following actions. It would be stored in the variable unknown_words.

capture_output_stale_words

Capture stale words as an action output so it can be used in following actions. It would be stored in the variable stale_words.

capture_output_skipped_files

Capture skipped files as an action output so it can be used in following actions. It would be stored in the variable skipped_files.

experimental_commit_note

Used as the commit body when a commit is created.

only_check_changed_files

If you don't specify only_check_changed_files: 1, check-spelling will check all files that aren't filtered by only / excluded.

Some repositories are quite large and typically have very few files changing at once. Assuming a good baseline, or a willingness to force people to fix all typos in a file as they touch it, one can use this flag (in v0.0.20+) to dramatically improve the time it takes to run.

With only_check_changed_files: 1, only the files changed (either by a PR, or since the previous commit tracked by GitHub for the branch/tag) will be checked.

Downside: if someone changes any of the config files, it's likely that they will have changed files that aren't being checked and you won't find out until they're touched at a later date. This can be frustrating for contributors (although, any linter can be frustrating).

dictionary_source_prefixes

As of v0.0.20, this holds a single prefix cspell which maps to https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20220427/dictionaries/.

Future versions will select different tags for cspell, and you can mix and match them, e.g.:

        dictionary_source_prefixes: '{"cspell": "https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20220427/dictionaries/","cspell1": "https://raw.githubusercontent.com/check-spelling/cspell-dicts/v20220814/dictionaries/"}'
        extra_dictionaries:
          cspell:lorem-ipsum/dictionary.txt
          cspell1:software-terms/src/software-terms.txt

Warning If you don't override check_extra_dictionaries, you'll want to ensure that cspell: maps to something that has each of the items in it, otherwise check-spelling will be a bit upset...

Used with extra_dictionaries / check_extra_dictionaries to define supplemental dictionary urls in a compact form.

extra_dictionaries

Extra dictionaries to be used when looking for unknown words.

This is a list of urls, additional url prefixes are defined by dictionary_source_prefixes.

See Area dictionaries.

check_extra_dictionaries

After unknown words are identified, they can be checked against additional dictionaries.

This enables users to choose additional dictionaries to add to extra_dictionaries in future runs.

extra_dictionary_limit

In order to not drown in check_extra_dictionaries suggestions, only this number of dictionaries are suggested in reports. The rest are available in the generated artifact. If you find the number of listed dictionaries isn't sufficient, you can increase this number.

event_aliases

GitHub has many events, and Check Spelling isn't specifically designed for most of them. If you want to use it with an event that it doesn't recognize, you can map the event to one it does. As long as the event has enough fields to work, Check Spelling will treat it as if it is the mapped even.

This is mostly because pull_request_target was added by GitHub and realistically one should have been able to use Check Spelling with it based on its support for the pull_request event long before it was updated to use the pull_request_target event.

suppress_push_for_open_pull_request

When running from a push event, check's to see if there's an open pull_request for the same branch. If there is, it will stop the current run, yielding a message explaining it didn't actually check spelling and report a ✅.

The actual Check Spelling pass will happen in the pull request event (as long as it's properly configured and it's mergeable).

report_title_suffix

When running in a matrix configurations, each section will produce its own comment.

The report_title_suffix enables each comment to have a distinct bit to help hint that the comment is not just an accidental duplicate.

warnings

check-spelling defaults to defining certain events as errors and others as warnings. If you disagree with these values, you can change the mapping by using this field.

See Treat specific errors as warnings for more information.

notices

v0.0.21

check-spelling defaults to defining certain events as errors and others as warnings. As with warnings, if you disagree with these values, you can change the mapping by using this field.

See Treat specific errors as warnings for more information.

custom_task

In order to run with restricted permissions under pull_request_target, check-spelling is split between two phases:

check-spelling which has limited permissions but would include potentially untrusted content (this is the default task)
comment this phase should have permission to post a comment (but the untrusted content shouldn't be checked out)

Replaced by task.

internal_state_directory

As part of custom_task, the default task returns its internal state. This needs to be passed to the custom_task: comment phase.

Use this parameter to indicate where the internal state was stashed.

Generally stashing is done via actions/upload-artifact@v2 and unstashing via actions/download-artifact@v2, but the action itself doesn't care, so if you want to use something else, you can.

check_file_names

People misspell file names too. If you want, Check Spelling can complain about them too. Feature: Check filenames and paths

anonymize_secpoll_source

As of 0.0.19, Check Spelling will check to see if the action is known to be unsafe to use. It does this using a DNS query.

If you don't want your DNS provider to be disclosed to the DNS servers hosting check-spelling, you can use this flag to ask it to pick a public dns server.

I don't expect anyone to use this feature, since on average check spelling runs inside GitHub hosted runners which means the IP addresses are incredibly uninteresting (and I have no intention of setting up a DNS server that logs queries).

That said, if you're running it in your own private infrastructure and want to be sure I can't check, you can use this flag.

ignore_security_advisory

If the version of Check Spelling you're using is insecure, you really should update.

By default, Check Spelling will not run if it believes it's unsafe.

It's possible there isn't a fixed version available (this shouldn't be for very long), and perhaps you're using a private repository where you trust everyone. If that's the case, you can use this flag to override the security advisory.

Please don't use this flag. In general, it's a really bad idea to run known unsafe code.

A couple of typos are probably a better tradeoff than running known unsafe code for a short interval.

largest_file

This is a file size limit in bytes. Files larger than this will be ignored.

unknown_word_limit

Each instance of an unknown word up to this limit will be reported.

GitHub will try to attach annotations for the first couple of reported items.

The downside of this limit, of course, is that if there are more instances of a given misspelled word than this limit, you will have to find the others on your own and fix them as well. (Or just iterate with the action until it's happy...)

See Limit reports for each unknown word

Files

Note that each of the below items can either be a file with a .txt suffix, or a directory, where each file with a .txt suffix will be merged together.

File	Description
advice	This allows you to supplement the comment.
allow	This allows you to supplement the dictionary.
dictionary	This allows you to replace the dictionary.
excludes	This allows you to skip checking files/directories.
expect	This defines the list of words in the repository that aren't in the dictionary.
forbidden	This allows you to define patterns of unacceptable strings.
only	This allows you to limit checking to certain files/directories.
patterns	This allows you to define patterns of acceptable strings.
reject	This allows you to remove items from the default dictionary.

advice

This adds a supplemental portion to the comment posted to GitHub. It's freeform. You can use it to explain how contributors should decide where to put new entries.

See Configuration Examples: advice for examples.

allow

This allows you to add supplemental words to the dictionary without replacing the core dictionary. One word per line.

They're really words, just not in the ancient base dictionary. They might not be used today in your project, but there's no reason for the spell checker to complain to a contributor tomorrow because it's foreseeable that they might be.

Some candidates:

every html tag & attribute
the name of everyone in your company (and the name of your company)
names of css attributes/properties
C or JavaScript reserved words
The names of all types/ functions from the C standard library

See Area dictionaries for other examples.

For entire reusable lists that don't live in your repository, you can use extra_dictionaries instead.

dictionary

This replaces the default dictionary. One word per line.

If you want to include the default dictionary, place it into the directory next to your own.

Alternatively, if you want to retrieve a dictionary from a remote URL, see the workflow configuration values dictionary_url and dictionary_version.

If you just want to supplement the dictionary, you can use extra_dictionaries or allow.

excludes

This file contains Perl regular expressions. Generally, one regular expression per line. They are merged using an OR (|).

Note that these are generally case-sensitive unless you explicitly use (?:(?i)...) or [Gg]it[Hh]ub or similar.

Files matching these patterns will be skipped.

See Configuration Examples: excludes for examples.

Lines that start with # will be ignored.

expect

This contains of expected "words" that aren't in the dictionary, one word per line.

Some arbitrary strings that are in test files that aren't really words. They should be removed if the test are changed/removed.

Expected words that are not otherwise present in the corpus will be suggested for removal, but will not trigger a failure.

Words that are present (i.e. not matched by the excludes file) in the repository and which are not listed in the expect list will trigger a failure as part of push and pull_request actions (depending on how you've configured this action).

comments in expect

You can use # followed by text to add a comment at the end of a line. Note that some automatic pruning may not properly handle this.

expect - previous name

:warning: This was previously called whitelist -- that name is deprecated. Support for the deprecated name may be removed in a future release. Until then, warnings will be reported in the action run log. At a future date, comments may report this as well.

Allow vs Expect

Roughly if it's a proper noun of some sort of exists in the real world outside the project, it's a good candidate for allow. If it's just something you're temporally using that isn't really a word, it probably belongs in expect.

Note

The bot doesn't really care. You could put everything into allow or everything into expect. The difference is that the bot will help you remove unused items from expect and add new items to it. You could also periodically migrate items from expect to allow (think about it like Java object lifespan promotions).

forbidden

Note: the file name is currently line_forbidden.patterns instead of forbidden.txt

This file contains Perl regular expressions. Generally, one regular expression per line. Lines that begin with # will be skipped. They are merged using an OR (|).

Note that these are generally case-sensitive unless you explicitly use (?:(?i)...) or [Gg]it[Hh]ub or similar.

Tokens within files that match these expressions will be flagged.

See Configuration Examples: forbidden for examples.

only

This file contains Perl regular expressions. Generally, one regular expression per line. They are merged using an OR (|).

Files not matching these patterns will be skipped.

See Configuration Examples: only for examples.

Lines that start with # will be ignored.

patterns

This file contains Perl regular expressions. Generally, one regular expression per line. Lines that begin with # will be skipped. They are merged using an OR (|).

Note that these are generally case-sensitive unless you explicitly use (?:(?i)...) or [Gg]it[Hh]ub or similar.

Tokens within files that match these expressions will be skipped.

See Configuration Examples: patterns for examples.

reject

This allows you to remove words from the dictionary without having to replace the core dictionary.

The order of operations is:

(dictionary + allows) - reject

See Configuration Examples: reject for examples.

disable_checks

Introduced after v0.0.20:

This is a comma-delimited list of flags:

noisy-file - Scan noisy files
word-collating - Disable word collating

check_commit_messages

⚠️ While check-spelling will be able to identify typos, any items you add to expect.txt will be suggested for removal once your PR merges, which will be very confusing. This feature will be reworked in a future release.

Introduced in v0.0.21

Check commit / PR metadata

You can specify multiple values

Value	Check
`commit`	The commit message for the latest commit
`commits`	The commit messages for pending commits
`title`	The PR title
`description`	The PR description

use_magic_file

Introduced in v0.0.21

Quickly check if files are binary and skip them if they are.

(This is off by default because enabling it by default would be a behavior change and it would be hard to allow users to override it.)

use_sarif

Introduced in v0.0.21

See Feature: Sarif output. This can be used as an alternative to having the tool generate comments on PRs / commits (i.e. you could remove the comment jobs).

It integrates with GitHub's SARIF analysis and reporting.

The sarif reports can be made available for download (the spell-check-this sample workflow does this).

Note that GitHub's defaults to not making it easy for people who aren't collaborators to a repository to see reports, so the experience may be slightly bumpy for projects w/ external contributors.

summary_table

Introduced in v0.0.22

Include a Summary Table in the Step Summary.

See Feature: Summary Table

report-timing

Introduced in v0.0.22

Generate a csv file with the start and stop time for each processed file.

Note that there can be multiple threads running and the precision is fairly low so it's very easy for a number of files to all have the same start and stop times.

See Feature: Timing Report

alternate_engine

For testing a different version of check-spelling, generally from a private repository. See also alternate_engine_key

alternate_engine_key

ssh key to use to check out the alternate_engine.

cache-dictionaries

This enables consumers to disable Feature: Cache dictionaries.

caller_container

act Hack to enable passing check-spelling job data from one check-spelling job to another.

        caller_container: ${{ needs.spelling.outputs.docker_container }}

candidate_example_limit

v0.0.22

Control how many lines are reported for each pattern suggestion.

checkout

check-spelling workflows often need write access in order to perform various actions (adding PR comments, adding commit comments, generating SARIF reports) and having write access is a bit of a pain for pull requests from foreign repositories (see Configuration: Workflows pull_request_target for the various combinations).

With checkout: 1, the check-spelling action will use actions/checkout to check out the repository and check-spelling/checkout-merge to get the merged commit instead of requiring the workflow to include the messy logic.

bucket

See Configuration: Advanced.

project

See Configuration: Advanced.

debug

See Configuration: Advanced.

ignore-pattern

Part of Feature: Configurable word characters.

lower-pattern

Part of Feature: Configurable word characters.

not-lower-pattern

Part of Feature: Configurable word characters.

not-upper-or-lower-pattern

Part of Feature: Configurable word characters.

punctuation-pattern

Part of Feature: Configurable word characters.

upper-pattern

Part of Feature: Configurable word characters.

quit_without_error

Prevent check-spelling from exiting with an error code.

spell_check_this

repository containing check-spelling metadata to use when the current checkout doesn't have any. This is mostly useful for Feature: Easier bootstrapping.

ssh_key

The ssh key to use to check out the repository (when using checkout), this enables Feature: Update with deploy key to work smoothly.

If the value isn't set (e.g. because it points to an undefined secret), the code will rely on contents: write in order to update the repository.

task

In order to run with restricted permissions under pull_request_target, check-spelling is split between two phases:

check-spelling which has limited permissions but would include potentially untrusted content (this is the default task)
comment this phase should have permission to post a comment (but the untrusted content shouldn't be checked out)

Used to pass messages between multiple check-spelling stages, especially from a stage that doesn't have write permissions to one that does (to add a comment, collapse a comment). This is mostly an implementation detail and shouldn't be specified directly.