diff --git a/.github/workflows/docs-to-issues.yml b/.github/workflows/docs-to-issues.yml index 0f15924a..1a815e77 100644 --- a/.github/workflows/docs-to-issues.yml +++ b/.github/workflows/docs-to-issues.yml @@ -343,7 +343,9 @@ jobs: git config --local user.email "github-actions[bot]@users.noreply.github.com" git config --local user.name "github-actions[bot]" git add docs/issues/ - git diff --staged --quiet || git commit -m "chore: move processed issue files to created/ [skip ci]" + # Removed [skip ci] to allow CI checks to run on PRs + # Infinite loop protection: path filter excludes docs/issues/created/** AND github.actor guard prevents bot loops + git diff --staged --quiet || git commit -m "chore: move processed issue files to created/" git push - name: Summary diff --git a/docs/plans/current_spec.md b/docs/plans/current_spec.md index 56efc7af..13b7aa25 100644 --- a/docs/plans/current_spec.md +++ b/docs/plans/current_spec.md @@ -1,8 +1,277 @@ # Current Specification -**Status**: ✅ Complete - Ready for Next Task +**Status**: 🔴 ACTIVE - Docs-to-Issues CI Skip Investigation **Last Updated**: 2026-01-11 -**Previous Work**: CI/CD Workflow Analysis - GitHub Security Warning & Supply Chain Verification +**Current Work**: Resolving PR #461 CI check failures caused by docs-to-issues workflow + +--- + +## Active Investigation: Docs-to-Issues CI Skip Problem + +**Priority:** 🔴 HIGH - Blocking PR validation +**Reported:** PR #461 +**Reference:** https://github.com/Wikid82/Charon/pull/461/changes/8bd0f9433a8455a1e2adb62ea80095488b8746ad + +### Problem Statement + +The `docs-to-issues.yml` workflow is preventing CI checks from appearing on PRs when it runs, breaking the PR review and merge process. + +**Observed Behavior:** +1. When docs-to-issues workflow triggers on a PR, it creates an automated commit +2. The commit message contains `[skip ci]` flag +3. GitHub interprets this as "skip ALL CI workflows for this commit" +4. No required status checks run on the PR +5. PR cannot be properly validated or merged + +**Impact:** +- **Blocks PR merges** - Required status checks never run +- **Breaks validation pipeline** - Tests, linting, security scans don't execute +- **Defeats CI/CD purpose** - Changes go unverified + +### Root Cause Analysis + +**Workflow Location:** `.github/workflows/docs-to-issues.yml` + +**Problem Line:** Line 346 +```yaml +git commit -m "chore: move processed issue files to created/ [skip ci]" +``` + +**Why [skip ci] Exists:** +The workflow uses `[skip ci]` to prevent an infinite loop: +1. Workflow runs on `push` to `docs/issues/**/*.md` +2. Creates GitHub issues from markdown files +3. Moves processed files to `docs/issues/created/` +4. Commits the file moves back to the same branch +5. Without `[skip ci]`, this commit would trigger the workflow again → infinite loop + +**GitHub's [skip ci] Behavior:** +- **Scope:** `[skip ci]` skips ALL workflows triggered by `push` events for that commit +- **Alternative Syntax:** `[ci skip]`, `[no ci]`, `[skip actions]`, `***NO_CI***` +- **Documentation:** https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs + +**Why This Breaks PRs:** +- GitHub requires status checks to pass on the **latest commit** of a PR +- When the latest commit has `[skip ci]`, the required workflows don't run +- GitHub shows "Waiting for status to be reported" indefinitely +- PR is blocked from merging + +### Current Workflow Behavior + +**Trigger Conditions:** +```yaml +on: + push: + branches: + - main + - development + - feature/** + paths: + - 'docs/issues/**/*.md' + - '!docs/issues/created/**' +``` + +**Process Flow:** +1. Detects new/modified markdown files in `docs/issues/` +2. Parses frontmatter (title, labels, assignees) +3. Creates GitHub issues via API +4. Moves processed files to `docs/issues/created/YYYYMMDD-filename.md` +5. Commits file moves with `[skip ci]` +6. Pushes commit to same branch + +**Protection Mechanism:** +- `if: github.actor != 'github-actions[bot]'` - Prevents bot-triggered loops +- `[skip ci]` - Prevents push-triggered loops + +### Investigation Results + +**Other Workflows That Commit:** + +1. **auto-versioning.yml** (Line 69): + - Creates and pushes tags: `git push origin "${TAG}"` + - **No [skip ci]** - but only pushes tags, not commits + - Tags don't trigger `on: push` workflows + +2. **propagate-changes.yml**: + - Creates PRs instead of committing directly + - **No [skip ci]** - uses PR mechanism instead + - Avoids the problem entirely + +3. **auto-changelog.yml**: + - Uses `release-drafter` action (no direct commits) + - **No [skip ci]** - doesn't create commits + +**Pattern Analysis:** +- ✅ **Best Practice:** Create separate PRs for automated changes (propagate-changes) +- ✅ **Alternative:** Use tags instead of commits (auto-versioning) +- ❌ **Anti-pattern:** Direct commits with [skip ci] (docs-to-issues) + +### Solution Options + +#### Option 1: Remove [skip ci] + Add Path Filter (RECOMMENDED) + +**Changes:** +1. Remove `[skip ci]` from commit message +2. Add path exclusion to workflow trigger: + ```yaml + on: + push: + paths: + - 'docs/issues/**/*.md' + - '!docs/issues/created/**' # Already present + ``` +3. Rely on existing `github.actor != 'github-actions[bot]'` guard + +**Pros:** +- ✅ CI checks run normally on PRs +- ✅ Still prevents infinite loops (path filter + actor guard) +- ✅ Minimal code changes +- ✅ No workflow complexity increase + +**Cons:** +- ⚠️ Adds one extra workflow run per docs-to-issues execution (the file move commit) +- ⚠️ Slight increase in Actions minutes usage (~30 seconds per run) + +**Risk Assessment:** LOW +- Path filter already excludes `docs/issues/created/**` +- Actor guard prevents bot loops +- Double protection against infinite loops + +#### Option 2: Create Separate PR for File Moves + +**Changes:** +1. Instead of committing directly, create a PR with file moves +2. Use `actions/github-script` to create PR via API +3. Auto-merge PR or leave for manual review + +**Pros:** +- ✅ No [skip ci] needed +- ✅ CI runs on all commits +- ✅ Audit trail via PRs +- ✅ Follows propagate-changes pattern + +**Cons:** +- ❌ High complexity - requires significant refactoring +- ❌ Creates many auto-PRs (noise) +- ❌ Slower - PR review process adds delay +- ❌ Requires CPMP_TOKEN or similar for auto-merge + +**Risk Assessment:** MEDIUM +- More moving parts +- Could create PR spam +- Requires additional token management + +#### Option 3: Don't Commit File Moves + +**Changes:** +1. Remove the "Move processed files" and "Commit moved files" steps +2. Let files remain in `docs/issues/` after processing +3. Add `.gitignore` for processed files or manual cleanup + +**Pros:** +- ✅ No [skip ci] needed +- ✅ Simplest solution +- ✅ CI runs normally + +**Cons:** +- ❌ Processed files accumulate in `docs/issues/` +- ❌ No clear separation of pending vs. completed +- ❌ Requires manual cleanup or gitignore maintenance +- ❌ Loses historical record of when issues were created + +**Risk Assessment:** MEDIUM +- Defeats organizational purpose of the workflow +- Clutters the docs/issues directory + +#### Option 4: Use [skip ci] Only on Main/Development + +**Changes:** +1. Add conditional to only skip CI on protected branches: + ```yaml + - name: Commit moved files + run: | + if [[ "${{ github.ref }}" == "refs/heads/main" || "${{ github.ref }}" == "refs/heads/development" ]]; then + git commit -m "chore: move processed issue files [skip ci]" + else + git commit -m "chore: move processed issue files" + fi + ``` + +**Pros:** +- ✅ CI runs on PRs (feature branches) +- ✅ Skips CI on main/dev (reduces noise) +- ✅ Balanced approach + +**Cons:** +- ⚠️ Still causes double runs on feature branches +- ⚠️ Adds branch-specific logic complexity + +**Risk Assessment:** LOW +- Good compromise solution +- Preserves optimization on main branches +- Enables validation on PRs + +### Recommended Solution: Option 1 (Remove [skip ci]) + +**Justification:** +1. **Solves the problem completely** - CI checks will run on PRs +2. **Low risk** - Multiple safeguards prevent infinite loops +3. **Minimal changes** - One-line modification +4. **Performance impact is negligible** - ~30 seconds extra per run +5. **Aligns with CI/CD principles** - All changes should be validated + +**Implementation Steps:** + +1. **Modify `.github/workflows/docs-to-issues.yml` line 346:** + ```yaml + # BEFORE: + git commit -m "chore: move processed issue files to created/ [skip ci]" + + # AFTER: + git commit -m "chore: move processed issue files to created/" + ``` + +2. **Verify safeguards are in place:** + - ✅ Line 45: `if: github.actor != 'github-actions[bot]'` + - ✅ Lines 11-12: Path exclusions for `docs/issues/created/**` + +3. **Test on feature branch:** + - Create test markdown file in `docs/issues/test-issue.md` + - Push to feature branch + - Verify workflow runs and creates issue + - Verify file moves to `created/` + - Verify commit triggers ONE more workflow run + - Verify second run skips (no files in `docs/issues/`) + - Verify CI checks appear on PR + +4. **Monitor for infinite loops:** + - Check workflow run history + - Confirm only 2 runs per docs change (original + file move) + - No cascading triggers + +### Success Criteria + +- ✅ CI checks run and appear on PRs when docs-to-issues workflow executes +- ✅ No infinite workflow loops occur +- ✅ File moves still happen correctly +- ✅ Issues are still created properly +- ✅ PR #461 can be validated and merged +- ✅ No increase in workflow failures + +### Rollback Plan + +If Option 1 causes problems: +1. Revert commit (one-line change) +2. Implement Option 4 (conditional [skip ci]) as fallback +3. Re-test on feature branch + +### Documentation Updates + +After implementation: +- [ ] Update `.github/workflows/docs-to-issues.yml` with inline comments +- [ ] Document decision in implementation summary +- [ ] Update CHANGELOG.md +- [ ] Add note to workflow documentation (if exists) ---