Skip to content
Skills Library
DevOps & cloud · Planning

building-a-github-action

/building-a-github-action

Use FIRST when building, extending or reviewing a GitHub Action, a release/publish pipeline, or any Effect v4 program that talks to the GitHub API, to decide which @effected package owns a capability and which skill teaches it. Answers which service handles a capability, whether the kit already ships it, and what the modern @effected equivalent of a legacy Actions toolkit call is. Also use when: build a GitHub Action, new action, action.yml, GITHUB_TOKEN, GitHub App token, workflow command, job summary, check run, cache in an action, upload an artifact, publish to npm from CI, SBOM, attestatio

Repository
effected ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use FIRST when building, extending or reviewing a GitHub Action, a release/publish pipeline, or any Effect v4 program that talks to the GitHub API, to decide which @effected package owns a capability and which skill teaches it. Answers which service handles a capability, whether the kit already ships it, and what the modern @effected equivalent of a legacy Actions toolkit call is. Also use when: build a GitHub Action, new action, action.yml, GITHUB_TOKEN, GitHub App token, workflow command, job summary, check run, cache in an action, upload an artifact, publish to npm from CI, SBOM, attestatio

Original author description

Use FIRST when building, extending or reviewing a GitHub Action, a release/publish pipeline, or any Effect v4 program that talks to the GitHub API, to decide which @effected package owns a capability and which skill teaches it. Answers which service handles a capability, whether the kit already ships it, and what the modern @effected equivalent of a legacy Actions toolkit call is. Also use when: build a GitHub Action, new action, action.yml, GITHUB_TOKEN, GitHub App token, workflow command, job summary, check run, cache in an action, upload an artifact, publish to npm from CI, SBOM, attestatio

How it works

  1. Designing or structuring a new action? Start elsewhere first
  2. I need to… → reach for…
  3. Call sequences — when the capability is a chain, not one service
  4. Standards
  5. What the kit deliberately does not ship
  6. Present, and easy to miss
  7. The suite
Original SKILL.md headings · 139 lines, 2,462 words
SKILL.md preview
---
name: building-a-github-action
description: "Use FIRST when building, extending or reviewing a GitHub Action, a release/publish pipeline, or any Effect v4 program that talks to the GitHub API, to decide which @effected package owns a capability and which skill teaches it. Answers which service handles a capability, whether the kit already ships it, and what the modern @effected equivalent of a legacy Actions toolkit call is. Also use when: build a GitHub Action, new action, action.yml, GITHUB_TOKEN, GitHub App token, workflow command, job summary, check run, cache in an action, upload an artifact, publish to npm from CI, SBOM, attestation"
---

# Building a GitHub Action

The routing map for the five `@effected` packages an action-shaped program uses: `@effected/github-actions` (the runner), `@effected/github` (the GitHub API), `@effected/commands` (subprocesses and tool discovery), `@effected/npm` (registry reads and publishing), and `@effected/sbom` (SBOM, in-toto, SLSA, Sigstore). Rows route to a skill; they do not teach the pattern themselves.

**The design boundary that matters most**: `@effected/github` talks to the GitHub API; `@effected/github-actions` talks to the runner it executes inside. Nothing in `github-actions` reads `process.env.GITHUB_REPOSITORY` on `github`'s behalf, and nothing in `github` imports a workflow command. The two meet at exactly two seams, both living in `github-actions`: the token bridge (`GitHubToken`) and the `Logger` that maps `Effect.log*` onto workflow commands (`ActionLogger.logger`).

A sixth package and its command sit beside them: `@effected/schemastore` (a runtime `dependency` — the action reads its output contract's `HostedSchema` identity from it to write `$schema`) and `@effected/schemastore-cli` (a `devDependency`; `schema:build` / `schema:check` publish and drift-test the JSON Schema, and it is where ajv lives so the bundle never carries an engine). For a capability outside these six — globs, semver, lockfiles, JSONC/YAML/TOML, XDG paths, git introspection, managed file sections — consult `effected-packages` before hand-writing it.

## Designing or structuring a new action? Start elsewhere first

This table routes a capability to the package and skill that own it; it does not sequence a build or lay out a repository. For a new action, a wholesale rebuild, or a port where more than one pipeline step changes, load `designing-an-action` first: recon → frozen parity contract → API dossier → contracts-first walking skeleton → TDD fill. For where a piece of code belongs — an entry point, a step, a shared service, a shim — load `structuring-an-action`: `designing-an-action` owns the order you build in, `structuring-an-action` owns the shape you build into. Return to this table during either sequence to look up which package and skill owns each piece as you build it.

## I need to… → reach for…

| I need to… | Reach for | Skill |
| --- | --- | --- |
| turn a fresh copy of the template into my action | the interview: identity, phases, access, inputs, outputs, capabilities, reporting, self-dogfood → a plan file | `bootstrapping-an-action` |
| decide where a piece of code belongs in the repo | the canonical tree: entries, `program.ts`, `steps/`, `services/`, `shims/`, `schema/`, `state.ts`, `format.ts` | `structuring-an-action` |
| write `main.ts` / `pre.ts` / `post.ts`, wire layers | `Action.run`, `ActionRuntime.layer`, `ActionServices` | `actions-runtime` |
| read an input, validate it, apply a default | `ActionInput` + Effect `Config` | `actions-inputs-outputs` |
| set an output, export a variable, add to PATH | `ActionOutputs` | `actions-inputs-outputs` |
| emit a machine-readable output contract | `ActionOutputs.setJson` + the same `Schema` codec | `actions-inputs-outputs` |
| publish and drift-test that contract's JSON Schema | `HostedSchema` beside the schema, `defineConfig` in `lib/scripts/schemastore.config.ts`, `schemastore build` / `check` | `actions-inputs-outputs` |
| make the run log readable | `ActionLogger` (`group`, nesting-aware; `withBuffer`, `notice`, `annotated`) | `actions-reporting` |
| write the job summary | `ActionOutputs.summary` | `actions-reporting` |
| read a published package's contents before installing it | `PackageTarball.extract` (scoped) + `resolveEntryPoint` | `release-and-publish` |
| create a check run or annotate a PR | `CheckRun`, `CheckRun.withCheckRun` | `actions-reporting` |
| post or update a sticky PR comment | `PullRequestComment.upsert` + `CommentMarker` | `actions-reporting` |
| write GitHub-flavored markdown / a findings table | `GitHubMarkdown`, `GitHubMarkdown.tableFor` | `actions-reporting` |
| maintain a sticky-comment or PR-description document | `ManagedDocument` (marker-delimited regions) | `actions-reporting` |
| reconcile check state onto a living document | `CheckDocument` + `CheckState` / `projectCheckState` | `actions-reporting` |
| read the webhook event payload | `ActionEnvironment.payload` | `actions-runtime` |
| pass a value from `pre` to `main` to `post` | `ActionState` | `actions-state-and-secrets` |
| handle a secret without leaking it | `Secret`, `Redacted`, `Redaction` | `actions-state-and-secrets` |
| decide whether a failure should fail the run | `Action.run`'s contract, `DryRun` | `actions-state-and-secrets` |
| kill a background process started in `main` | `DetachedProcess.reap` | `actions-state-and-secrets` |
| safely prepend a directory to a spawned child's PATH | `ChildEnv.prependPath` | `actions-state-and-secrets` |
| call any GitHub REST or GraphQL endpoint | `GitHubClient.request` / `.graphql` / `.paginate` | `github-api` |
| create a branch, tag, release, commit, PR | the resource services (`GitBranch`, `GitTag`, …) | `github-api` |
| write an Actions / Dependabot / Codespaces / environment **secret** | `RepositorySecret` — encrypts client-side with a sealed box; the value is `Redacted` and GitHub never returns it | `github-api` |
| read or write an Actions or environment **variable** | `RepositoryVariable` | `github-api` |
| create or update a repository **ruleset** | `Ruleset.upsert` — matches on name **and** `source_type`, so a repository-scoped write cannot overwrite an inherited organization ruleset | `github-api` |
| manage deployment **environments** | `DeploymentEnvironment` | `github-api` |
| toggle vulnerability alerts, automated fixes, private reporting | `RepositorySecurity` — each has its own endpoint | `github-api` |
| configure CodeQL default setup, or read repository languages | `CodeScanning` | `github-api` |
| change repository settings | `GitHubRepository.updateSettings` (the typed PATCH) or `applySettings` (an open map routed across REST **and** the GraphQL mutation, returning the fields it actually sent) | `github-api` |
| ask whether a repository owner is a user or an org | `GitHubRepository.ownerType` | `github-api` |
| ask whether a repository has **workflows** | `WorkflowDispatch.list` — repository *languages* come from linguist and can never report `actions`, which GitHub validates against workflow files | `github-api` |
| render a DCO sign-off trailer on a bot commit | `BotIdentity.signoff` | `github-api` |
| authenticate as a GitHub App | `GitHubApp`, `GitHubApp.clientLayer` | `github-app-tokens` |
| mint a token in `pre` and revoke it in `post` | `GitHubToken` provision → read → dispose | `github-app-tokens` |
| cache a directory between runs | `ActionCache` | `actions-cache-and-artifacts` |
| upload or download a workflow artifact | `Artifact` | `actions-cache-and-artifacts` |
| store a blob (Actions cache or S3-compatible) | `BlobStore`, `GitHubCacheBlobStore`, `BlobEnvelope` | `actions-cache-and-artifacts` |
| install a toolchain on the runner | `ToolInstaller` | `actions-cache-and-artifacts` |
| pin and install an exact npm/pnpm/yarn/bun | `PackageManagerInstaller` | `actions-cache-and-artifacts` |
| compute a cache key from file contents | `CacheKey` | `actions-cache-and-artifacts` |
| run a subprocess and get a typed result | `Run.collect` / `text` / `lines` / `json` | `running-commands-and-tools` |
| ask whether a CLI tool is installed | `ToolDiscovery` | `running-commands-and-tools` |
| run a local binary in a workspace or a bare repo | `LocalExec` | `running-commands-and-tools` |
| read a registry: latest version, dist-tags, times | `NpmRegistry` | `release-and-publish` |
| pack and publish a package | `PackagePublish`, `NpmExecutor` | `release-and-publish` |
| derive a release tag or a tracking tag | `ReleaseTag`, `VersioningStrategy` | `release-and-publish` |
| hold a release back by age | `ReleaseAgeGate` | `release-and-publish` |
| emit an SBOM | `Sbom.generate` / `toJson` / `write` | `supply-chain-attestation` |
| sign an artifact and attest a build | `SigstoreSigner`, `SlsaProvenance`, `Attestation.upload` | `supply-chain-attestation` |
| get an OIDC token from the runner | `OidcTokenIssuer` | `supply-chain-attestation` |
| publish with a workload credential minted from the runner's identity | `ActionsRegistryCredential.workload` → `PackagePublish.setupAuth` | `release-and-publish` |
| capture SLSA provenance from the runner's claims | `ActionsProvenance.capture` | `supply-chain-attestation` |
| serve `oidc`'s identity contract (what `sbom`'s signer needs) from the runner | `ActionsIdentityToken.layer` | `supply-chain-attestation` |
| test any of the above | `makeTest` / `layerTest` on every service | `testing-actions` |

## Call sequences — when the capability is a chain, not one service

| I need to… | Call sequence | Packages |
| --- | --- | --- |
| sign and store an attestation | `SlsaProvenance.forGitHubWorkflow` → `InTotoStatement.forSubject` → `SigstoreSigner.sign` → `Attestation.upload` | `sbom` + `github` |
| publish a package, integrity-checked | `NpmRegistry.version` (already-published probe) → `PackagePublish.setupAuth` → `PackagePublish.pack` → `PackagePublish.publishTarball` | `npm` |
| read a config dependency before install runs | `NpmRegistry.version` → `PackageTarball.extract` (scoped) → `resolveEntryPoint` | `npm` + `package-json` |
| hold a token across the three phases | `GitHubToken.provision` (pre) → `GitHubToken.read` (main) → `GitHubToken.dispose` (post) | `github-actions` |
| emit an SBOM and attest it | `Sbom.generate` → `Sbom.toJson` → `InTotoStatement.forSubject` → `SigstoreSigner.sign` → `Attestation.upload` | `sbom` + `github` |

## Standards

- **Resolve an API claim in order**: the package's own `CLAUDE.md`, then its source — the source wins on disagreement. For Effect core itself, load `effect-v4-source-lookup`: the vendored source settles existence and signature, a probe settles semantics.
- **The route is the key.** `client.request("GET /repos/{owner}/{repo}", …)` types the parameters and response from the literal alone; a cast in GitHub API code is a defect, not a shortcut.
- **Every service ships `makeTest`/`layerTest`**, and an unstubbed member dies loudly, naming itself. A handful of recorded exceptions each carry a stated reason.
- **Errors are `Schema.TaggedError`, in one of two shapes — check which before writing a handler.** Most carry a discriminant field and are matched on it: `kind` (`GitHubError`, `PublishError`, `RegistryReadError`, `CommandFailedError`, `CheckDocumentError`, `ManagedDocumentError`, `TokenPermissionError`, `GitHubAppError`) or `reason` (`ActionEnvironmentError`, `GitHubTokenError`, `BlobTransferError`). Four in `@effected/github-actions` are instead **per-reason tagged unions**: `ActionOutputError`, `BlobEnvelopeError`, `CacheKeyError` and `DetachedProcessError` are `type` aliases over one exported class per failure, matched on `error._tag`, with `Effect.catchTag` recovering from one arm rather than all of them. Every name still appears in the same signatures, so a union is invisible until you reach for `.reason` — which no longer type-checks on those four. Every error reason has a test that fires it; when porting a channel, demonstrate its failure path or delete it from the signature.
- **Read an input through `ActionInput`, never a bare `Config.*` read spelled by hand.** `ActionInput` carries the parsing and the typed `ConfigError`s a bare read cannot, and a test suite that injects its own `ConfigProvider` around a bare read can silently diverge from the runner's own key derivation.
- **A consumer program never mentions the platform.** `ActionRuntime.layer` composes the platform and HTTP client internally with no requirements of its own, and an extra layer handed to `Action.run` may require anything the runtime already provides.
- **`@effected/github-actions` is the one package in the kit with a required Node platform peer, and the only one where a raw `node:` import is sanctioned** — for digests and HMAC, reaping a bare pid, a file-descriptor-level detached spawn, and the cache/artifact codecs. Sanctioned is not unlimited: everything that can go through a core contract does.
- **Heavy engines stay confined, and it is measured, not promised.** Azure to a handful of modules, Sigstore to one, octokit to `@effected/github`, each with a reachability test carrying a control. Never gather a heavy engine into a namespace object, never route it through a shared internal helper, and never fold it into a default runtime.
- **The bundler and the scaffold are a separate concern.** This suite teaches the code an action is made of, not how it is bundled or scaffolded — a template repository owns that layer.

## What the kit deliberately does not ship

- No `@actions/core`, `@actions/cache`, `@actions/artifact`, or any `@actions/*` package — the protocols are implemented directly against their own APIs.
- No `MainLive`/`PreLive`/`PostLive` exports — those are an action's own naming convention for its per-entry layers, built from `ActionRuntime.layer` plus each service's `static readonly layer`; the kit ships no such consts.
- No standalone inputs service or a distinct input-error type — inputs are `Config`-based, and input failures are `ConfigError`.
- No rate-limiter subsystem or proactive throttling — one `RetryPolicy` lives inside the client, and `client.rateLimit` exposes the headers for a caller that wants to pace itself.
- No per-resource error classes — one `GitHubError` carries a `kind` discriminant.
- No separate GraphQL client construct — GraphQL is a member of the client.
- No report-shaping construct — but **`GitHubMarkdown` does ship the GFM writer** (`table`, `tableFor(schema)`, `heading`, `link`, `code`, `codeBlock`, `list`, `details`, `raw`), from `@effected/github-actions`, and `ManagedDocument` / `CheckDocument` ship the document surfaces. "Shaping" means the arrangement of a report — which facts, in which order — not the primitives. Never hand-roll a markdown writer: compose `GitHubMarkdown` pieces, or reach for `@effected/markdown` for a document you build as a tree. See `actions-reporting`.
- No fan-out-and-accumulate construct — `Effect.partition(items, f)` returns `[successes, failures]` and never fails; `Effect.all(effects, { mode: "result" })` is the per-effect form.
- No ANSI/colour API — GitHub's log viewer colours the workflow commands itself; do not invent one.
- No shared `*Test` module family or a `./testing` subpath — every service ships its own `makeTest`/`layerTest`. Grep the installed packages for `makeTest` to see the current set; it is large, not a handful.
- No named log-level resolver — `Action.run` already lowers `References.MinimumLogLevel` to `Debug` under `RUNNER_DEBUG=1` (opt out with `{ stepDebugLogLevel: false }`). For the raw flag, obtain the service and read its member — `const env = yield* ActionEnvironment; const stepDebug = yield* env.isDebug` — never `ActionEnvironment.isDebug`, which is not a static. See `actions-runtime`.

## Present, and easy to miss

These exist, and each one has been mistaken for a gap at least once. A capability filed under the absence list above when it actually ships is the expensive misreading — one build planned a hand-rolled markdown writer off exactly that mistake.

- **`GitHubMarkdown` (capital H)** — the GFM writer: `table`, `tableFor(schema)`, `heading`, `link`, `code`, `codeBlock`, `list`, `details`, `raw`.
- **`ActionInput.string("x")`** — the accessor owns the `INPUT_` derivation; you never spell it yourself.
- **`Service.makeTest` / `Service.layerTest`** — on the service itself, not on a `/testing` subpath.
- **`ActionRuntime.layer`** — the composed runtime; never hand-compose a `MainLive`.

## The suite

| Skill | Owns |
| --- | --- |
| `actions-runtime` | entry points, `Action.run`, layer wiring, failure rendering |
| `actions-inputs-outputs` | `ActionInput`, `ActionOutputs`, output contracts |
| `actions-reporting` | logs, annotations, summaries, check runs, PR comments |
| `actions-state-and-secrets` | `ActionState`, `Secret`, `DryRun`, `DetachedProcess`, `ChildEnv` |
| `actions-cache-and-artifacts` | `ActionCache`, `Artifact`, `BlobStore`, `ToolInstaller`, `PackageManagerInstaller`, `CacheKey` |
| `github-api` | the client, routes, pagination, resilience, the error taxonomy, resources |
| `github-app-tokens` | `GitHubApp`, the client constructors, the `GitHubToken` bridge |
| `running-commands-and-tools` | `Run`, `ToolDiscovery`, `LocalExec`, `Redaction`, `Retry` |
| `release-and-publish` | `NpmRegistry`, `PackagePublish`, tags, versioning, release gates |
| `supply-chain-attestation` | SBOM, NTIA, in-toto/SLSA, OIDC, Sigstore, `Attestation` |
| `testing-actions` | the doubles convention, the octokit harness, the domain's mutants |
| `designing-an-action` | the build sequence: recon, frozen parity contract, API dossier, walking skeleton, TDD fill |
| `bootstrapping-an-action` | the user-invoked interview that turns the template into a planned action and hands off to `designing-an-action` |
| `structuring-an-action` | the canonical repo tree, structural standards, where a piece of code belongs |

For the general Effect v4 rules these all sit on — schema design, service and layer form, core idioms, observability, testing — load `effect-v4-schema`, `effect-v4-services-layers`, `effect-v4-idioms`, `effect-v4-observability` and `effect-v4-testing`. This suite carries only the GitHub-specific instances.

Versions

The database has no other skills named building-a-github-action.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version d53cf4b67cee (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100designing-an-action
    Use when designing a NEW GitHub Action, rebuilding or porting an existing action onto the @effected suite, or planning any multi-step action build, before writing the spec, the plan, or any module. For a single feature added to an existing action, load the matching actions-*…
  • 100testing-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…
  • 100github-actions-style
    GitHub Actions workflow and composite action conventions for MLflow. Use when writing, modifying, or reviewing workflows in .github/workflows/ or actions in .github/actions/ in this repository.
  • 100review-ci
    Use when the user asks for a CI review, CI/CD review, GitHub Actions review, workflow review, pipeline review, build pipeline audit, "review the workflows", "review the actions", action pinning audit, workflow permissions audit, or supply-chain review of CI configuration.
  • 100publish-npm-package
    Use if publishing to npm via GitHub Actions — trusted publishing, provenance, semantic-release.
  • 100deployment-pipelines
    Use when authoring or reviewing CI/CD pipelines — GitHub Actions workflows, reusable workflows, composite actions, OIDC federation to AWS/GCP, caching, artifacts, and pipeline security hardening. Triggers on edits to .github/workflows/**, action.yml, composite action…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.