fix: remove [skip ci] from commit message to allow CI checks on PRs
This commit is contained in:
GitHub Actions
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user