/lint-workflows

Lint GitHub Actions Workflows

Reference: Load ci-conventions skill and references/linter-rules.md for rule details (W01-W14).

Step 1: Find Workflows

If $ARGUMENTS specifies a file:

• Validate the path — reject if it contains .., starts with / or ~, or contains characters outside [a-zA-Z0-9._/-]. Respond: "Invalid file path: must be a relative path within the repository."
• Verify the resolved path is within .github/workflows/. Respond: "Path must point to a file inside .github/workflows/."
• Verify file exists; respond: "File not found: <path>" if missing
• Lint that file only

Otherwise:

• Find all files: Glob: .github/workflows/*.yml and .github/workflows/*.yaml
• If none found: "No workflow files found in .github/workflows/"

Step 2: Read and Analyze

For each workflow file, check these rules:

Errors (must fix):

• W01: Job without timeout-minutes → suggest timeout-minutes: 60
• W07: Missing runs-on: self-hosted label when repo uses self-hosted runners
• W13: Using actions/cache@v2 or @v3 → upgrade to @v4

Warnings (should fix):

• W02: Package install step without caching → suggest ecosystem-appropriate cache
• W03: Hardcoded /home/runner/ paths → use ${{ github.workspace }}
• W04: PR-triggered workflow without concurrency group
• W05: Docker usage without cleanup step
• W06: ubuntu-latest in repo with self-hosted runner jobs
• W10: actions/checkout without clean: true on self-hosted
• W11: Matrix strategy without fail-fast: false
• W12: Deploy job without environment field
• W14: Cleanup/teardown steps without if: always()

Info:

• W08: upload-artifact without retention-days

Step 3: Report Findings

Group by severity (Error → Warning → Info). For each finding:

• File path and line number
• Rule ID and description
• Whether auto-fixable
• Suggested fix

Example output:

## Lint Results: .github/workflows/ci.yml

### Errors (2)
- **W01** Line 12: Job `build` missing `timeout-minutes`
  Fix: Add `timeout-minutes: 60` ✅ Auto-fixable
- **W13** Line 25: Using `actions/cache@v2` (outdated)
  Fix: Update to `actions/cache@v4` ✅ Auto-fixable

### Warnings (1)
- **W04** Line 1: No concurrency group for PR workflow
  Fix: Add concurrency block ✅ Auto-fixable

Step 4: Offer Auto-Fix

If auto-fixable findings exist:

• Use AskUserQuestion: "Apply auto-fixes? [All / Select individually / Skip]"
• If applying: use Edit tool for each fix, show diff
• After applying: re-read file to verify YAML validity

Error Handling

If YAML syntax error:

• Report parse error with approximate line
• Suggest fixing syntax before linting rules

If workflow uses reusable workflows (uses: ./.github/workflows/):

• Note: lint applies to caller workflow only, not called workflow