View on GitHub


Documentation for check-spelling


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.


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:


Default: .github/actions/spelling

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


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.


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.


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.

See check-spelling/spell-check-this @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.


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.


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.


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.


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.


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


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 stale words as an action output so it can be used in following actions. It would be stored in the variable stale_words.


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


Used as the commit body when a commit is created.


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


As of v0.0.20, this holds a single prefix cspell which maps to

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

        dictionary_source_prefixes: '{"cspell": "","cspell1": ""}'

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


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.


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.


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.


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


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.


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.



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.


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

Replaced by task.


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.


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


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.


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.


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


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


Introduced after v0.0.20:

This is a comma-delimited list of flags:


⚠️ 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


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


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.


Introduced in v0.0.22

Include a Summary Table in the Step Summary.

See Feature: Summary Table


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


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


ssh key to use to check out the alternate_engine.


This enables consumers to disable Feature: Cache dictionaries.


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

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



Control how many lines are reported for each pattern suggestion.


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.


See Configuration: Advanced.


See Configuration: Advanced.


See Configuration: Advanced.


Part of Feature: Configurable word characters.


Part of Feature: Configurable word characters.


Part of Feature: Configurable word characters.


Part of Feature: Configurable word characters.


Part of Feature: Configurable word characters.


Part of Feature: Configurable word characters.


Prevent check-spelling from exiting with an error code.


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


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.


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

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.

Configuration Files

See Configuration Files



See Configuration Files: Advice


See Configuration Files: Allow

block delimiters

See Configuration Files: Block Delimiters


See Configuration Files: Dictionary


See Configuration Files: Excludes


See Configuration Files: Expect


See Configuration Files: Forbidden


See Configuration Files: Only


See Configuration Files: Patterns


See Configuration Files: Reject

FAQ | Showcase | Event descriptions | Configuration information | Known Issues | Possible features | Deprecations | Release notes | Helpful scripts