actions-inputs-outputs
Use when reading a GitHub Action's inputs through ActionInput, writing outputs through ActionOutputs, or designing a machine-readable, schema-backed output contract for a workflow or LLM consumer.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8
- Forks
- 2
01 前言 Front Matter
- name
- actions-inputs-outputs
- description
- Use when reading a GitHub Action's inputs through ActionInput, writing outputs through ActionOutputs, or designing a machine-readable, schema-backed output contract for a workflow or LLM consumer.
- when_to_use
- action input, action output, INPUT_ mangling, action.yml sync, ActionManifest, runner-shaped inputs, ConfigError, dry-run silently defaulted, runner file delimiter, setJson, output contract, JSON Schema drift test, ActionInputs service, ActionInputError, schemastore, SchemaPipeline, published output schema, versioned schema
02 资源文件 3
- 参考文档references/input-validation.md10.8 KB
- 参考文档references/json-contracts.md2.7 KB
- 参考文档references/output-contracts.md20.7 KB
03 SKILL.md 正文
Actions inputs & outputs
The runner-file I/O surface of @effected/github-actions: reading what a workflow author configured, and publishing what the action produced. Both modules fail through structured errors, and neither ever spells a runner variable name — that mangling lives in exactly one function per direction.
For everything else the runtime provides — ActionState, Secret, GitHubToken, the default layer composition — see actions-runtime. For Redacted/masking mechanics and cross-phase state, see actions-state-and-secrets. For the job summary sink and log annotations beyond setFailed/setSecret, see actions-reporting. For test doubles, see testing-actions. General Effect v4 Config/Schema rules live in effect-v4-schema and effect-v4-idioms; this skill carries only the Actions-specific instance of those rules.
What you have
| Construct | Import | Reach for it when |
|---|---|---|
ActionInput.string / .boolean / .integer / .redacted |
import { ActionInput } from "@effected/github-actions" |
reading a single-value input with the runner's own parsing rules |
ActionInput.lines / .list / .pairs |
same | reading a multi-value or key/value input without hand-rolling a splitter |
ActionInput.schema(name, schema) |
same | an input carries genuinely nested structure and is worth decoding as JSON |
ActionOutputs.set / .exportVariable / .addPath |
import { ActionOutputs } from "@effected/github-actions" |
publishing a plain output, an env var for later steps, or a PATH prefix |
ActionOutputs.setJson |
same | publishing a structured output through a Schema codec |
ActionOutputs.summary |
same | appending to the job summary (full sink detail in actions-reporting) |
ActionOutputs.setFailed / .setSecret |
same | rendering ::error::/::add-mask:: directly, outside the normal failure path |
Standards
- Read every input through
ActionInput's accessors — never a bareConfig.String/Config.Booleanspelled by hand. The accessors own theINPUT_name mangling (uppercase, spaces to underscores, dashes survive) and carry the parsing and typedConfigErrors a bare read cannot.ActionRuntime.layerinstalls a provider that also resolves a bare flat name through the same derivation, but a program that reads inputs directly still owns none of the parsing — writeActionInput.boolean("dry-run"), notINPUT_DRY-RUNspelled anywhere. - Prove a present-but-malformed input fails through
withDefault.Config.withDefault/Config.optionclassify a missing key as absent, but a present, unparseable value still fails —Configtracks input evidence itself, not the issue (InvalidValuecarries noactualfield to build a stale "missing" classification from; its constructor is(annotations?, input?, options?)). A present-but-malformed value fails even under a default: keep the regression test (config.pipe(Config.withDefault(x))fails, not falls back, on malformed input). Seereferences/input-validation.md. - Design a state or output field's encoded form as plain JSON before deciding how to test it. A
setJsonpayload, a runner-file write, and cross-phase state all round-trip throughJSON.stringify/parse; a value whose encoded form isn't a JSON primitive fails one step later than the mistake. - Build a
CheckRunOutput/ActionOutputsobject with a conditional spread when a field isoptionalKey. The key may be omitted; the value must never be an explicitundefinedpassed to it. - Publish a
setJsoncontract from a schema the projection also produces from — never duplicate the shape. Seereferences/output-contracts.md. - An empty string reads as absent, everywhere in this surface. The runner sets an unsupplied optional input to
""; treat that the same as a missing key, not a supplied empty value.
Footguns
- A bare
Config.String("dry-run")can typecheck, compile clean, and pass a test suite whose injectedConfigProvideris keyed by the plain name — and still read nothing against the real runner, silently falling back to a default. Seereferences/input-validation.md. - GitHub uppercases and replaces spaces with underscores in a runner variable name, but dashes survive — a hand-written test key with underscores where dashes belong reads nothing and passes for the wrong reason. See
references/input-validation.md. ActionEnvironmentsnapshotsprocess.envonce at layer construction, so a value exported mid-run throughexportVariableis never observed by the same process's own reader — that's GitHub's model, not a bug. Assert against the writtenGITHUB_ENVfile, not a same-process readback.- A runner-file block write uses a derived delimiter, never a fixed or random one — a value containing an un-derived delimiter would terminate its own block early and corrupt every entry written after it in the same file.
Additional resources
- references/input-validation.md — the
Config.withDefaulttrap in full, theinputVariablemangling rule with its dash/underscore trap, the two config providers (layerDefaultvs the record-backedlayer()), the three-way sync discipline betweenaction.yml, an input names tuple and the decoded shape, andActionManifest(difffor the name check,runnerInputsfor the runner-shaped test environment) so none of it is hand-rolled. Load when: designing or reviewing an inputs module, or chasing why a malformed input silently defaulted. - references/output-contracts.md —
ActionOutputs' full member table, the runner-file delimiter and name-validation rules, and the pattern for asetJsonpayload consumed outside the action: schema as encoder, pure projections, where the document's title and description go on aSchema.Class, publication through aHostedSchemaidentity andlib/scripts/schemastore.config.tswith theschemastorecommand (apublisheddocument refuses a contract change at its current label), versioned publication, which custom annotation keys survive, andschema:checkas the drift gate. Load when: authoring or reviewingActionOutputsusage, or asetJsonoutput meant for a downstream job, a bot, or an LLM reader. - references/json-contracts.md — when a JSON-shaped input earns a published,
@effected/schemastore-generated JSON Schema versus staying an internalActionInput.schemadecode. Load when: an input is genuinely nested structure rather than a flat or line-list value, and workflow authors would benefit from editor completion on it.
04 同仓库更多 Skills
testing-actions
Use when writing or reviewing tests for @effected/github-actions, @effected/github, @effected/sbom or @effected/commands — stubbing the GitHub API, writing a service's layerTest or makeTest double, testing the pre/main/post lifecycle through Action.run, or debugging why a test hits the real network or hangs.
supply-chain-attestation
Use when generating a CycloneDX SBOM, checking NTIA minimum elements, building an in-toto statement or a SLSA provenance predicate, signing into a Sigstore DSSE bundle, or uploading an attestation to GitHub.
structuring-an-action
Use when laying out a new GitHub Action repository on the @effected suite, deciding where a piece of code belongs (an entry point, a step, a shared service, a shim), or reviewing an existing action's file structure against the canonical shape.
running-commands-and-tools
Use when running a subprocess in Effect v4, spawning a command, capturing stdout/stderr/exit code, checking whether a CLI tool is installed or which copy to run, running a package-manager script through the project's launcher, detaching a background process, or redacting a secret from argv or captured output.
release-and-publish
Use when publishing a package to npm, reading the npm registry from Effect v4, checking whether a version is already published, cutting a release tag or GitHub release from an action, applying a release-age gate, or deriving tracking tags for GitHub Actions distribution.
hardening-a-parser-port
Use when porting or writing a recursive-descent parser, lexer, or tree-walker over untrusted text in the @effected monorepo — the class of hardening the cloud reviewer scans for on every migration. Covers stack-overflow depth guards (on EVERY recursion surface, which a facade has N of — not two), numeric bound guards that must reject NaN and non-integers, code-point range checks scoped to formats with wide escapes, prototype-pollution, control-character rejection, and the invariant that malformed input must fail through the typed error channel, never as an unhandled defect.