@sidj-thr/actions-ci

CI utilities — a modular, extensible CLI for GitHub automation. Replaces inline YAML scripts with tested, versioned Node.js commands.

Installation

npm install @sidj-thr/actions-ci

Or run directly in a GitHub Actions step:

- run: npx @sidj-thr/actions-ci pending-approvals --pr-number ${{ github.event.pull_request.number }}

Usage

actions-ci <command> [flags]

Commands:
  pending-approvals   Check PR approval status and post a review-status comment

Flags:
  --help, -h          Show help
  --version, -v       Show version

Commands

pending-approvals

Checks whether a PR has the required approvals from the right roles (Management/Team Lead and Members), then upserts a ## Review Status comment on the PR summarising the current state.

actions-ci pending-approvals \
  --pr-number 123 \
  --maintainers-team management \
  --team-leads-team team-leads \
  --min-approvals 2

Flag	Description	Default
--pr-number	PR number to check (required)	—
--repo	owner/repo string	$GITHUB_REPOSITORY
--maintainers-team	GitHub team slug for Management (required)	—
--team-leads-team	GitHub team slug for Team Leads (required)	—
--min-approvals	Minimum total approvals required	2

Exits with code 1 if the PR is not yet approved.

Comment format

The command upserts a single ## Review Status comment on the PR. Examples of what it posts:

Approved:

## Review Status
**Current Status: ✅ APPROVED**
Approvals so far: Management: 1, Team Lead: 1

Pending — missing codeowner approval:

## Review Status
**Current Status: ❌ PENDING**
Approvals so far: Member: 1

Pending reviews: Needs 1 Management or Team Lead.

Pending — codeowner present but total below threshold:

## Review Status
**Current Status: ❌ PENDING**
Approvals so far: Management: 1

Pending reviews: Needs 1 more from Management, Team Lead, or Member.

Zero-count roles are omitted from the summary line. If the comment already exists (identified by the ## Review Status marker) it is updated in-place rather than creating a new one.

Environment variables (required)

Variable	Description
GITHUB_TOKEN	Token used to post the review-status comment
GITHUB_APP_ID	GitHub App ID used for team membership resolution
GITHUB_PRIVATE_KEY	GitHub App private key (PEM)

Secrets are never accepted as CLI flags. They must be supplied via environment variables. This prevents tokens from appearing in the process list (ps aux), shell history, or CI log echoes.

Example GitHub Actions step

- name: Check PR approvals
  env:
    GITHUB_TOKEN: ${{ secrets.CI_TOKEN }}
    GITHUB_APP_ID: ${{ secrets.APP_ID }}
    GITHUB_PRIVATE_KEY: ${{ secrets.APP_PRIVATE_KEY }}
  run: |
    npx @sidj-thr/actions-ci pending-approvals \
      --pr-number ${{ github.event.pull_request.number }} \
      --maintainers-team management \
      --team-leads-team team-leads \
      --min-approvals 2

Security model

Threat	Mitigation
Token in process list	Secrets are env-only; no --token flag exists
Token in shell history	Same — nothing to type
Token in CI log echo	Same — nothing to echo
Token in error messages	sanitizeError() + redact() on all output
CodeQL taint flow argv→API	validatePrNumber() + validateRepo() applied before every call
Prototype pollution via argv	paparam used (no minimist); paparam does not expose raw prototype-writable objects
Dependency CVEs	Minimal runtime deps; run npm audit before releasing
Secrets in test files	All network calls mocked; fixture tokens are fake sentinel values
Stack trace leaking secrets	err.message only, never err.stack

How to add a new subcommand

1. Create lib/commands/<name>/index.js:

   'use strict'
   const { command, flag, summary, footer } = require('paparam')
   const { Command } = require('../../command')
   const { validatePrNumber, sanitizeError, exitWithError } = require('../../helpers')
   const { myDomainFn } = require('./helpers')
   
   class MyCommand extends Command {
     constructor () {
       super({
         name: 'my-command',
         description: 'One-line description for --help',
         secrets: [
           { envVar: 'MY_SECRET', description: 'Token for ...' }
         ]
       })
     }
   
     toCommand () {
       const cmd = command(
         'my-command',
         summary(this.description),
         flag('--some-flag <value>', 'A flag'),
         footer(this._secretsFooter()),
         async () => {
           try { await this.run(cmd.flags) }
           catch (err) { exitWithError(sanitizeError(err)) }
         }
       )
       return cmd
     }
   
     async _run (flags) {
       // secrets already validated by base class
       // validate inputs first
       // call helpers — never pass secrets as arguments
     }
   }
   
   module.exports = new MyCommand()

2. Create lib/commands/<name>/helpers.js — domain logic. Read secrets from process.env inside functions; never pass them as parameters.

3. Register in main.js — add one line:

   const myCommand = require('./lib/commands/my-command/index')
   // ...
   const prog = command(
     'actions-ci',
     // ...
     pendingApprovals.toCommand(),
     myCommand.toCommand()   // ← add this
   )

4. Write tests in test/unit/<name>-index.test.js and test/unit/<name>-helpers.test.js. Mock all network calls. Use fake sentinel tokens (ghp_FAKE_TOKEN_FOR_TESTING_ONLY_...) — they match the redact() pattern and let you test redaction logic.

Nothing in the framework layer (main.js, lib/command.js, lib/helpers.js) needs to change unless you are adding new generic behaviour that should be available to all commands.

Development

# Install dependencies
npm install

# Run tests
npm test

# Lint
npm run lint

# Lint + auto-fix
npm run lint:fix

# Check for dependency vulnerabilities
npm run audit

Publishing

This package has no build step — it is plain Node.js CJS with no compilation or bundling required.

npm publish automatically runs npm test first via the prepublishOnly hook, so a failing test suite will abort the publish before anything reaches the registry.

# Publish to npm (runs tests automatically first via prepublishOnly)
npm publish

In CI, tests should also run in a dedicated job before the publish job, so failures are caught at PR time rather than at publish time.

Requirements

Node.js >=18.0.0

License

Apache-2.0