RFC: Check action that surfaces arkenv check --json in GitHub Actions

[yamcodes]

Summary

A setup-arkenv action would not earn its keep. arkenv is a project dependency, not a runner toolchain. arkenv check loads that repo’s env.ts, which imports @arkenv/core or @arkenv/standard from that project’s node_modules. After install, pnpm exec arkenv check is already the CI step, and the check reference shows it.

The GitHub-specific gap is presentation. --json already emits a settlement envelope (diagnostics, nextActions, exit 0 / 2 / 4). In Actions that envelope is a blob in the job log. A check action could map it onto workflow annotations and the job summary, where a reviewer sees the failing keys without scrolling the log.

Ship it only if that UI is clearly better than the log the CLI already prints. If it is not, the run: line stays the integration.

What it would do

Run after the workflow’s own checkout, runtime setup, and install. Call the project’s arkenv (the node_modules/.bin entry), so the CLI version stays in package.json next to @arkenv/core. Pass through flags the workflow already uses (--schema, --env-file, --verify-example, --quiet). The workflow keeps owning env: and secrets.

Read the stdout envelope and:

• Fail the step on exit 4 (findings; envelope is still ok: true) and exit 2 (could not run; ok: false). Exit 0 passes.
• Write a job summary from each diagnostic: code, summary, why, and nextActions labels.
• Emit a workflow annotation only when diagnostic.where points at a file in the checkout (line when present). --verify-example against .env.example is the case that has a real file. A missing DATABASE_URL in the job environment usually has no checked-in line, so it belongs in the summary, not a fake file annotation.
• Keep values redacted. The envelope is already redaction-safe; the action must not print process.env or secret values into annotations, the summary, or a comment.

Sketch:

- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
- uses: actions/setup-node@v4
  with:
    node-version: 22
    cache: pnpm
- run: pnpm install --frozen-lockfile
- name: Validate environment
  uses: yamcodes/arkenv-check-action@v1
  with:
    args: --verify-example
  env:
    DATABASE_URL: ${{ secrets.DATABASE_URL }}

A PR comment is optional and secondary. Annotations and the job summary need no extra permissions. A comment needs pull-requests: write and a token, which is a higher bar.

What it would not do

• Install Node, pnpm, or a global arkenv binary (setup-arkenv).
• Run arkenv init.
• Install dependencies or choose a package manager.
• Forward every GitHub secret into the check. Explicit env: stays the contract.
• Reimplement validation. The CLI remains the source of truth, including exit 4 for findings and dotted CLI.* / ENV.* codes.
• Parse env.ts itself, or lint .env syntax (that stays out of Check; see Discussion #1710).

Open questions

1. Is the job summary enough, or do file annotations for --verify-example change how you review a PR?
2. Should a PR comment exist at all, or does it duplicate the summary on every push?
3. One action with an args input, or two thin entry points (check and check --verify-example)?
4. Live in this repo (tag-driven composite action) or a separate action repo so library releases and the action tag do not move together?