inputs.md

order	120

Inputs and outputs

Every with: input the action accepts, and the outputs it sets for the steps after it. Every input is optional (the required column is always false); a default of "" is an unset input, and the description says what an omitted input means. The token grant is on the permissions page, the undeclared policies on the undeclared policy page.

A list input (sections, required-sections, repos, exclude, topics, affiliation, and settings-file in mode: render) takes newline- or comma-separated values. settings-file is split the same way in every mode, so no settings file path can contain a comma.

Inputs

name	description	required	default
token	The token for the API calls: a fine-grained PAT, since the default GITHUB_TOKEN can never hold the Administration grant most sections need.	false	${{ github.token }}
repository	The owner/name repository to run against, the current repository by default.	false	""
settings-file	The settings document to run, or in mode: render the ordered list of layers to fold, lowest first.	false	.github/settings.yml
mode	apply (write the file's settings), check (report drift, exit 1 on any), render (fold settings-file layers into rendered-file), or snapshot (write the live settings back as a settings file).	false	apply
rendered-file	mode: render only, and required there: the path the rendered settings document is written to.	false	""
snapshot-file	mode: snapshot only, for one repository: the path its live settings are written to as a settings document.	false	""
snapshot-dir	mode: snapshot only, for a fleet: the directory receiving one owner/name.yml per repos or repos-dir target.	false	""
on-missing-permission	fail (default) or warn: whether a section the token cannot access fails the run or is skipped with a warning.	false	fail
required-sections	Comma- or newline-separated sections that must fully apply even under on-missing-permission: warn.	false	""
sections	Comma- or newline-separated allowlist of the sections to process, every declared section when unset.	false	""
api-version	The X-GitHub-Api-Version header value, to opt into a newer REST API version before this action defaults to it.	false	2022-11-28
repos	Comma- or newline-separated owner/name targets, each applied from its own .github/settings.yml, or "*" alone to discover every repository the token's user owns.	false	""
repos-dir	A directory in the checked-out admin repository holding one settings file per target, as name.yml or owner/name.yml.	false	""
defaults-file	A settings document applied whole to every multi-repo target that has no settings file of its own.	false	""
layering	mode: render only: replace, shallow, or deep (default), how every list section's entries combine with the layers below them.	false	""
undeclared	keep or delete: the fallback for what apply does to a live resource a list does not declare, unset by default so each list's own default applies.	false	""
private-repos	redact (default) or show: whether private and internal targets are hidden from the run's public logs, summary, and outputs.	false	redact
private-report	none (default), issue, issue-on-failure, or artifact: the private channel that delivers the full report of each target the visibility probe proves private or internal.	false	none
report-public-key	The age recipient (a public key starting with age1) the artifact channel encrypts every report to, required by private-report: artifact and rejected otherwise.	false	""
visibility	Keeps only repositories of this visibility in repos: "*" discovery: all (default), public, private, or internal.	false	""
archived	Archived-repository policy for repos: "*" discovery: skip (default), include, or only.	false	""
forks	Fork policy for repos: "*" discovery: include (default), exclude, or only.	false	""
exclude	Comma- or newline-separated glob patterns removing repositories from repos: "*" discovery, compared case-insensitively against owner/name when the pattern has a "/" and against the name alone otherwise. A star matches any run of characters, "?" one character, "[abc]" one of a set, "[!abc]" or "[^abc]" one outside it, and one leading "!" negates the pattern. Beyond those a pattern holds only letters, digits, ".", "-", and "_", with at most one "/", nothing empty around it, and no side that is just "." or ".."; anything else (a leading "./", a run of stars, a regex token such as "(a)+") fails the run naming the fix.	false	""
topics	Comma- or newline-separated topics, of which repos: "*" discovery keeps the repositories carrying at least one.	false	""
affiliation	Comma- or newline-separated affiliations for repos: "*" discovery: owner (default), collaborator, or organization_member.	false	""

An input set outside its scope fails the run before any API call, naming the input and the fix. The mode-only inputs say so in their rows. Every other input mode: render or mode: snapshot refuses is listed in the render table and the snapshot table.

repository is refused beside repos or repos-dir, as is a settings-file other than its default, and defaults-file is refused without them. The multi-repo guide covers the two sourcing modes and the discovery filters that belong to repos: "*" alone.

Outputs

• result: failed / drift / partial / skipped / applied / clean / snapshot / rendered, worst first across the run's targets; the exit code is 1 exactly when it is failed, or drift in mode: check. The snapshot guide says what each snapshot word means, and skipped is a fleet target with no settings file and no defaults-file (the fallback).
• skipped-sections: the sections skipped for missing permissions under on-missing-permission: warn, comma-separated (a deduped union across targets in multi-repo mode); empty when none.
• repos-result: a JSON map of owner/name to {result, source, skipped-sections}, one entry per target of a multi-repo run (repos, repos-dir, or the snapshot-dir form of mode: snapshot); the empty map {} for a run over one repository or a render. A redacted private target is keyed by its private repository #N placeholder instead of its slug; see Private repositories.

All three outputs are set on every run, whatever the mode and however it ended.

A check run exits 1 on any drift, so a downstream step usually reads result only when the step runs with continue-on-error: true or through if: always(). Check mode has the exit-code table.

Environment variables

Beside the inputs, a run reads these from its environment. The Actions runner sets every GITHUB_* and ACTIONS_* name below except GITHUB_TOKEN, which a workflow exports itself; the command line reads every name here except ACTIONS_RUNTIME_TOKEN, under the same names: GITHUB_OUTPUT and GITHUB_STEP_SUMMARY only under GITHUB_ACTIONS=true.

Variable	Read for
GITHUB_TOKEN	The token when the token input (or --token) is empty
GITHUB_REPOSITORY	The default repository, the owner of a bare <name>.yml under repos-dir, and the one target never redacted
GITHUB_SERVER_URL, GITHUB_RUN_ID	The run link a private report carries
GITHUB_API_URL	The REST base URL (GitHub Enterprise Server)
GITHUB_ACTIONS	true on a runner: the command line then also appends its outputs to GITHUB_OUTPUT, writes the summary to GITHUB_STEP_SUMMARY (or to the file --summary names), and issues annotations as workflow commands
GITHUB_OUTPUT, GITHUB_STEP_SUMMARY	Where the action writes its outputs and the step summary (the command line writes them too under GITHUB_ACTIONS=true, --summary overriding the summary file; in a terminal it prints the outputs and writes the summary only to the file --summary names)
ACTIONS_RUNTIME_TOKEN	The artifact service's credential; private-report: artifact warns and uploads nothing without it (GitHub Enterprise Server)
GSAC_RETRY_BASE_MS	A test knob: the real milliseconds in one retry-backoff second. Set, it also selects the immediate scheduler, so the rate-limit Retry-After waits and the write limiter's spacing are skipped rather than scaled. Unset, a second is a second and the waits are real. Set it only to make a retry scenario finish in milliseconds against a mock; against GitHub the skipped waits earn the next secondary rate limit