Repository navigation
🌟 [Breaking change]: Unified CI and Release Workflow #198
Description
Primary User Story
As a PowerShell module maintainer managing multiple repositories, I need a single workflow configuration that automatically runs tests on pull requests and publishes releases when changes are merged to the main branch. This unified workflow eliminates the need to maintain two separate workflow files (CI.yml and workflow.yml) across all repositories, reducing configuration complexity and ensuring consistency.
Acceptance Scenarios
- Given a pull request is opened or updated, When the workflow runs, Then it MUST execute all CI tests without attempting any release operations
- Given a pull request is merged to the main branch, When the workflow runs, Then it MUST execute CI tests and proceed to release/publish operations if tests pass
- Given changes are pushed directly to the main branch (bypass PR), When the workflow runs, Then it MUST execute both CI tests and release operations
- Given CI tests fail on a PR, When the workflow completes, Then it MUST report failure status and NOT proceed to any release operations
- Given CI tests fail on main branch, When the workflow completes, Then it MUST report failure and halt before release operations
- Given a repository adopts this unified workflow, When migration is complete, Then maintainers MUST be able to remove separate CI.yml and workflow.yml files without losing functionality
Edge Cases
- What happens when a workflow is manually triggered (workflow_dispatch)?
- How does the workflow handle concurrent runs when multiple PRs are merged rapidly?
- What happens if release operations fail after CI tests pass on main branch?
- How does the workflow distinguish between testing-only and release-required contexts?
- What happens when a repository has custom test configurations or matrix strategies?
Requirements (mandatory)
Functional Requirements
| ID | Requirement |
|---|---|
| FR-001 | Workflow MUST trigger on pull request events (opened, synchronized, reopened) |
| FR-002 | Workflow MUST trigger on push events to the main branch |
| FR-003 | Workflow MUST execute CI test suite for all trigger events |
| FR-004 | Workflow MUST conditionally execute release operations only on main branch pushes |
| FR-005 | Workflow MUST skip release operations when running on pull request events |
| FR-006 | Workflow MUST report test results as PR status checks |
| FR-007 | Workflow MUST fail fast and halt execution if CI tests fail |
| FR-008 | Workflow MUST publish module releases to [NEEDS CLARIFICATION: target registry not specified - PowerShell Gallery, private feed, both?] |
| FR-009 | Workflow MUST create GitHub releases with [NEEDS CLARIFICATION: versioning strategy not specified - semantic versioning, date-based, manual tags?] |
| FR-010 | Workflow MUST be compatible with existing repository structures used in PSModule repositories |
| FR-011 | Workflow MUST support manual triggering (workflow_dispatch) with [NEEDS CLARIFICATION: should manual triggers allow release operations, or tests only?] |
| FR-012 | Workflow MUST handle authentication for [NEEDS CLARIFICATION: authentication targets not specified - PowerShell Gallery API keys, GitHub tokens, other credentials?] |
Non-Functional Requirements
| ID | Requirement |
|---|---|
| NFR-001 | Workflow MUST complete CI test phase within reasonable time limits [NEEDS CLARIFICATION: acceptable time limits not specified] |
| NFR-002 | Workflow MUST be maintainable as a single source of truth across multiple repositories |
| NFR-003 | Workflow MUST provide clear logging to distinguish CI and release phases |
| NFR-004 | Workflow MUST be idempotent for release operations (safe to re-run without duplicate publishes) |
| NFR-005 | Workflow configuration MUST be simple enough for module maintainers to understand and customize |
| NFR-006 | Workflow MUST minimize redundant work when transitioning from PR to main branch merge |
Quality Attributes Addressed
| Attribute | Target Metric |
|---|---|
| Maintainability | Single workflow file replaces two separate files; changes apply to all repositories via template updates |
| Reliability | Consistent behavior across all trigger scenarios; fail-safe design prevents accidental releases |
| Usability | Clear phase separation; easy to understand which operations run in which context |
| Efficiency | Reduced configuration overhead; faster onboarding for new repositories |
Constraints
| Constraint | Description |
|---|---|
| GitHub Actions | Must run on GitHub Actions platform using composite actions or reusable workflows |
| PowerShell Module Structure | Must work with PSModule repository structure conventions |
| Backward Compatibility | Must not break existing CI or release behaviors when migrating from separate workflows |
| Existing Actions | Must leverage existing PSModule GitHub actions (PSModule/GitHub-Script@v1, PSModule/Install-PSModuleHelpers@v1) |
Key Entities
| Entity | Description |
|---|---|
| Workflow Configuration | Single YAML file defining triggers, jobs, and conditional logic for CI and release phases |
| CI Phase | Test execution, validation, and quality checks that run on all events |
| Release Phase | Module publishing, GitHub release creation, and post-release operations that run only on main branch |
| Trigger Context | Runtime information determining whether workflow runs in PR mode or release mode |
| Test Results | Output from CI phase determining whether release phase can proceed |
Feature Branch: 001-merge-ci-release-workflows
Created: 2025-10-02
Status: Draft
Activity
[-]🚀 [Feature]: Unified CI and Release Workflow[/-][+]🌟 [Breaking change]: Unified CI and Release Workflow[/+]MariusStorhaug commentedon Oct 2, 2025
✅ Planning Phase Complete
Implementation plan and all design artifacts have been created:
Deliverables:
Constitutional Compliance: ✅ All principles verified
Pull Request: #199 (Draft)
Next Steps: Ready for task generation with
/taskscommand or implementation analysis with/analyzecommand.MariusStorhaug commentedon Oct 2, 2025
Clarification Session (2025-10-02)
All clarifications have been integrated into the specification.
Note: These clarifications were resolved during the research phase and have now been formally integrated into the spec to remove all [NEEDS CLARIFICATION] markers.
MariusStorhaug commentedon Oct 2, 2025
✅ Task list ready. Run
/analyzefor quality check or/implementto begin execution.Task Summary
Total Tasks: 28 tasks across 5 implementation phases
Phase Breakdown:
Execution Strategy:
Key Files:
.github/workflows/workflow.yml(sequential modifications T010-T015)Task List: Available in tasks.md
Pull Request: Updated with task checkboxes in #199
MariusStorhaug commentedon Oct 2, 2025
Analysis Report
Summary
High Priority Issues
Medium Priority Issues
Low Priority Issues
Coverage Summary
Coverage: 12 complete (66.7%), 2 partial (11.1%), 4 gaps (22.2%)
Next Actions
Recommended Actions (address HIGH priority issues):
Optional Improvements (MEDIUM priority):
Proceed with Implementation?
✅ YES - No critical issues block implementation. Address HIGH priority issues first (should take <30 minutes), then proceed with
/implementor manual task execution. MEDIUM/LOW issues can be addressed during or after implementation without blocking progress.Analysis Methodology: Cross-artifact semantic analysis comparing spec.md (18 requirements, 6 acceptance scenarios), plan.md (constitution check, technical context), tasks.md (28 tasks), and constitution.md (5 core principles). All findings are deterministic and reproducible.
MariusStorhaug commentedon Oct 2, 2025
✅ Task List Refined Based on Analysis
The task list has been updated to address the 5 high-priority issues identified in the analysis report:
Changes Made
Added:
Enhanced:
Removed:
Renumbered:
Task Count Update
Status
✅ Ready for Implementation
Three high-priority issues have been resolved (H2, H3, H5). The remaining issues can be addressed during or after implementation:
Next Action
Run
/implementto begin executing the 24 tasks.Commit: 36b087a