# Workflow Review Report — 2026-02-17

## Scope

This review covers the following top-level workflow files under `.github/workflows`:

- `buddy.yml`
- `ci.yml`
- `codeql.yml`
- `official.yml`
- `release-build-node-pack.yml`
- `release-build-python.yml`
- `release-build-ruby-gem.yml`
- `release-build-wxt.yml`
- `release-create-github-release.yml`
- `release-prepare-release-notes.yml`
- `release-resolve.yml`
- `renovate.yml` (reviewed only as a dependency-maintenance workflow outside
  release authority)

This report combines:

1. Design review (architecture, workflow orchestration, policy fit).
2. Code review (implementation details, safety, maintainability).
3. Clarifications from repository owner and their impact on findings.

---

## Review Baseline and Clarifications

The following points were explicitly clarified and are treated as **accepted policy**:

1. **Official release may publish a beta/RC package while GitHub Release is marked as non-prerelease** (`prerelease=false`).
2. **First-party actions (`actions/*`) do not need SHA pinning**; third-party actions should be pinned.
3. **Default timeout behavior is acceptable**; no requirement to add `timeout-minutes` everywhere.
4. **Full fetch/history/tags are required** because NBGV-based version calculation depends on them.

These clarifications supersede any earlier suggestions that conflict with them.

---

## Strengths Observed

- Clear orchestration split between entry workflows (`official.yml`, `buddy.yml`) and reusable workflows (`release-*`).
- Strong multi-language release flow coverage (Python, Node, Ruby, WXT) with unified input resolution via `release-resolve.yml`.
- Consistent defensive shell practices (`set -Eeuo pipefail`) across scripts.
- Artifact-centered release pipeline design: build -> verify -> publish -> release.
- Good use of minimal job permissions in many workflows.
- Version and artifact integrity checks are present in reusable build workflows.

---

## Validation Performed

### 1) Workflow syntax/problem check

No workflow-file errors were reported by editor diagnostics during review.

### 2) Third-party action pinning check (with first-party exception)

A repository-local scan was run against `.github/workflows/*.yml` using this rule:

- Allow unpinned refs for `actions/*`.
- Require full 40-char SHA pin for non-`actions/*` external actions.

Result: **No top-level third-party pinning violations found**.

---

## Findings Status

### Closed by Clarification (Not Issues)

The following items were previously discussed but are now considered closed due to explicit policy decisions:

- Official release stable/prerelease semantics mismatch concern.
- Requirement to SHA-pin first-party `actions/*` actions.
- Requirement to set explicit timeout for all jobs.
- Recommendation to reduce fetch depth/history in release resolution.

### Closed by Follow-up Changes (2026-02-18, updated for Renovate migration)

- Dependabot maintenance workflows were replaced by Renovate-native
  configuration.
- Lockfiles are handled by Renovate managers and lock-file maintenance;
  `global.json` regeneration is handled by Renovate post-upgrade tasks.

---

## Remaining Concerns

### 1) Duplication between `official.yml` and `buddy.yml`

There is significant parallel orchestration logic, which can drift over time.

**Severity:** Medium (maintainability).

**Suggested direction (optional):**

- Introduce one higher-level reusable orchestration workflow with policy inputs (`channel`, `prerelease flag behavior`, publish targets).
- Keep current `release-*` reusable building blocks and reduce top-level duplication.

### 2) Node matrix overlap in CI (optional optimization)

**File:** `ci.yml`

Matrix includes both a fixed `20.19.0` and floating `20.x`. This may be intentional; if not, there is potential CI-cost optimization.

**Severity:** Low.

### 3) Release notes may become overly verbose for large changelogs

**File:** `release-prepare-release-notes.yml`

When `CHANGELOG.md` exists, the workflow currently copies the whole file into release notes. This is valid, but long changelogs can reduce readability on the GitHub Release page.

**Severity:** Low.

**Optional improvement:**

- Extract only the target version section for `${PROJECT} v${VERSION}` when a structured changelog format is available.

### 4) Ruby system dependencies are installed in multiple workflows

**Files:** `ci.yml`, `release-build-ruby-gem.yml`

LaTeX/graphics dependencies are installed with `apt-get` in more than one place. This is functionally correct, but duplicates maintenance effort and can increase runner time.

**Severity:** Low.

**Optional improvement:**

- Consolidate shared package-install logic into one reusable composite action or shared script.

---

## Final Assessment

Given the accepted clarifications, the workflow suite is in good shape overall:

- Security posture is generally strong for a multi-language monorepo pipeline.
- Reusable workflow architecture is solid.
- Remaining concerns are mostly governance and maintainability, not immediate correctness blockers.

---

## Suggested Next Steps (If You Want Follow-up)

1. Decide whether to keep or simplify Node 20 dual coverage (`20.19.0` + `20.x`).
2. Consider a future refactor to reduce orchestration duplication between `official.yml` and `buddy.yml`.
3. Consider extracting shared Linux package-install logic for Ruby-related jobs into a reusable script/composite action.

---

Reviewed on: 2026-02-17
Repository: `hcoona/three`
Branch: `main`
