Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Pipeline Plan 204

ezigus edited this page Mar 20, 2026 · 2 revisions

Now I have a complete picture. Let me write the implementation plan.


Implementation Plan: GitHub Actions Quick-Start Generator

Current State Analysis

Two previous iterations have already built significant infrastructure:

  1. Commit 9a30ea9 — Created scripts/sw-ci.sh (725 lines), scripts/lib/ci-quickstart.sh (257 lines), scripts/sw-ci-test.sh (311 lines), modified scripts/sw-init.sh (--ci flag), modified scripts/sw-doctor.sh (--ci flag), and scripts/sw-doctor-test.sh
  2. Commit 85f0ee3 — Deleted 13 old hardcoded shipwright-*.yml workflow files (2,927 lines removed)

What's Already Working

  • shipwright ci quickstart generates workflow YAML from pipeline templates
  • shipwright init --ci delegates to shipwright ci quickstart
  • shipwright doctor --ci validates workflow files (structure, label trigger, artifact upload)
  • Project type detection (node/python/go/rust/ruby/java) with correct setup steps
  • --template, --test-cmd, --force flags
  • README section generation with badges
  • NO_GITHUB support in generated workflows (${{ vars.NO_GITHUB }})
  • 29 CI tests + 4 doctor --ci tests — all passing
  • Additional commands: generate, analyze, matrix, cache, secrets, reusable, badges, runners, validate

Alternatives Considered

Approach A (current): Bash-based generator with heredoc YAML templates

  • Pros: Consistent with codebase (all shell), no new dependencies, Bash 3.2 compatible
  • Cons: YAML generation in bash is fragile, harder to test edge cases
  • Blast radius: Only new files + small modifications to init/doctor

Approach B: Template files with variable substitution

  • Pros: Cleaner separation of template vs logic, easier to maintain YAML
  • Cons: More files to manage, more complex template engine in bash
  • Not chosen: Current approach already works and is tested

Chosen: Approach A — it's already implemented, tested, and follows codebase conventions.

Gaps Against Acceptance Criteria

Acceptance Criteria Status Gap
shipwright init --ci generates workflows Done
Issue label trigger, secrets check, artifact upload, status reporting Done
Auto-detects project type with test commands Done
README section auto-generated with badges Done
shipwright doctor --ci validates workflows Done
Works with NO_GITHUB=1 for air-gapped testing Partial Generated workflows check vars.NO_GITHUB, but sw-ci.sh itself doesn't guard GitHub API calls
Bash 3.2 compatibility Bug cmd_generate() uses ${var^} (Bash 4+ uppercase) at line 183
Secrets check in workflow Done
All templates supported (fast/standard/full/autonomous) Partial Default is fast,standard; all templates work but --template all isn't supported

Files to Modify

File Action Purpose
scripts/sw-ci.sh Modify Fix Bash 3.2 compat bug in cmd_generate(), add NO_GITHUB guard
scripts/lib/ci-quickstart.sh Modify Add secrets check validation, improve NO_GITHUB air-gapped support
scripts/sw-ci-test.sh Modify Add tests for NO_GITHUB mode, Bash 3.2 compat, edge cases
scripts/sw-doctor-test.sh Modify Add test for --ci with missing YAML sections
scripts/sw-doctor.sh Modify Add secrets reference validation to --ci check

Implementation Steps

  1. Fix Bash 3.2 compatibility bug in sw-ci.sh:183 — replace ${workflow_name^} with tr uppercase (same pattern used in ci-quickstart.sh:77-79)

  2. Add NO_GITHUB guard to sw-ci.sh — ensure cmd_quickstart() and cmd_generate() work fully offline without GitHub API calls; add NO_GITHUB=1 test case

  3. Add --template all support to cmd_quickstart() — allow generating workflows for all available templates at once

  4. Enhance doctor --ci validation — add checks for: secrets references (${{ secrets.* }}), workflow_dispatch trigger, permissions block

  5. Add edge case tests — empty template list, invalid template name, missing templates/ directory, NO_GITHUB mode quickstart

  6. Verify full test suite passes — run npm test and sw-ci-test.sh

Task Checklist

  • Task 1: Fix Bash 3.2 ${var^} bug in cmd_generate() — use tr pattern
  • Task 2: Add NO_GITHUB guards to sw-ci.sh for air-gapped operation
  • Task 3: Add --template all shorthand to cmd_quickstart()
  • Task 4: Enhance doctor --ci with secrets and permissions validation
  • Task 5: Add NO_GITHUB test in sw-ci-test.sh
  • Task 6: Add Bash 3.2 compat test for cmd_generate()
  • Task 7: Add edge case tests (invalid template, missing templates dir)
  • Task 8: Run full test suite and verify all tests pass

Testing Approach

Test Pyramid Breakdown

  • Unit tests (8 existing + 4 new): Test individual commands (quickstart, generate, validate, etc.) in isolation with mocked binaries
  • Integration tests (4 existing + 2 new): Test init --ci delegation, doctor --ci validation with generated workflows
  • E2E tests (0): Not applicable — would require real GitHub Actions runner; covered by NO_GITHUB mode

Coverage Targets

  • All cmd_* functions in sw-ci.sh: 100% happy path, key error paths
  • ci-quickstart.sh functions: all 3 functions (detect_project_for_ci, generate_quickstart_workflow, generate_readme_section)
  • Doctor --ci validation: all check branches (pass/warn/fail)

Critical Paths to Test

  • Happy path: quickstart generates valid YAML with correct structure for detected project type
  • Error: invalid template: quickstart --template nonexistent fails gracefully with available template list
  • Error: no jq: detect_project_for_ci returns "unknown" without jq
  • Edge: NO_GITHUB=1: All commands work without GitHub API access
  • Edge: empty repo: Detection returns "unknown", workflow uses placeholder test command

Risk Analysis

Risk Impact Mitigation
Bash 3.2 ${var^} bug breaks macOS cmd_generate() fails on default macOS bash Fix with tr pattern (Task 1)
Generated YAML has syntax errors Workflows fail to parse on GitHub Existing validate command + test coverage
Template path resolution breaks in installed vs dev mode Quickstart can't find templates ci-quickstart.sh already handles path resolution via _CI_QS_DIR
Old deleted workflows cause confusion Users on main still have old files Deletion is in the branch; clean break

Definition of Done

  • shipwright init --ci generates valid workflow YAML for all supported templates
  • shipwright ci quickstart works with --template, --test-cmd, --force flags
  • shipwright doctor --ci validates generated workflow configuration
  • All generated YAML includes: issue label trigger, secrets check, artifact upload, status reporting
  • Auto-detects project type (node/python/go/rust/ruby/java) with correct setup steps
  • README section generated with badges and usage instructions
  • Works with NO_GITHUB=1 for air-gapped testing
  • Bash 3.2 compatible (no ${var^}, no declare -A, no readarray)
  • All existing tests pass (sw-ci-test.sh: 29 tests, sw-doctor-test.sh: 24 tests)
  • New tests cover NO_GITHUB mode and edge cases

CLI Interface Specification

shipwright init --ci

shipwright init --ci [--template <list>] [--test-cmd <cmd>] [--force]

Delegates to shipwright ci quickstart with all remaining args.

shipwright ci quickstart

shipwright ci quickstart [--template <csv|all>] [--test-cmd <cmd>] [--force]
  • --template: Comma-separated list or all (default: fast,standard)
  • --test-cmd: Override auto-detected test command
  • --force: Overwrite existing workflow files

shipwright doctor --ci

shipwright doctor --ci

Validates: YAML structure, label trigger, artifact upload, secrets references, permissions block.

Error Codes

  • Exit 0: Success
  • Exit 1: Template not found, missing config, validation failure

Versioning

CLI follows VERSION="3.2.4" in all scripts. No API versioning needed (CLI tool, not HTTP API).

Rate Limiting

Not applicable (local CLI tool).

Clone this wiki locally

AltStyle によって変換されたページ (->オリジナル) /