PipeChecker

Catch CI/CD pipeline errors before you push — not after CI fails.

What Problem Does This Solve?

Every developer has been here:

💀 You push a small change → CI fails 10 minutes later →
   you fix it → push again → CI fails again → repeat 3 more times

PipeChecker runs locally and validates your CI/CD workflows before you commit, so you catch:

Catches	Example
❌ Circular dependencies	Job A → Job B → Job A
❌ Missing job references	`needs: [build]` but no `build` job exists
❌ Empty pipelines	No jobs or steps defined
⚠️ Hardcoded secrets	`API_KEY=sk_live_abc123` in env vars
⚠️ Undeclared env vars	`${{ env.UNKNOWN }}` never defined
⚠️ Unpinned actions	`uses: actions/checkout` without `@v4`
⚠️ Docker `:latest` tags	`image: nginx:latest` (unreproducible builds)
⚠️ Missing job timeouts	No `timeout-minutes` set — jobs can run forever
⚠️ Missing permissions	No `permissions:` block — inherits write-all token
⚠️ Missing concurrency cancel	Concurrency group without `cancel-in-progress`
⚠️ Static cache keys	`actions/cache` without `hashFiles(...)`
ℹ️ Missing retention-days	`actions/upload-artifact` with default 90-day retention

Visual Overview

┌─────────────────────────────────────────────────────────┐
│                    YOUR WORKFLOW FILE                    │
│              (.github/workflows/ci.yml)                  │
└────────────────────────┬────────────────────────────────┘
                         │
                         ▼
              ┌──────────────────────┐
              │    PIPECHECKER       │
              │                      │
              │  ┌────────────────┐  │
              │  │  YAML Parser   │  │
              │  │ GitHub/GitLab  │  │
              │  │   CircleCI     │  │
              │  └───────┬────────┘  │
              │          │           │
              │  ┌───────▼────────┐  │
              │  │    Auditors    │  │
              │  │                │  │
              │  │  📋 Syntax     │  │
              │  │  🔗 DAG/Cycle  │  │
              │  │  🔒 Secrets    │  │
              │  │  ⏱️  Timeout    │  │
              │  │  🔐 Permissions│  │
              │  │  📐 Schema     │  │
              │  │  🔄 Concurrency│  │
              │  │  📦 Artifacts  │  │
              │  │  🐳 Docker     │  │
              │  │  📌 Pinning    │  │
              │  └───────┬────────┘  │
              │          │           │
              └──────────┼───────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
     ✅ PASS       ⚠️ WARNINGS    ❌ ERRORS
   No issues     Fix before       Must fix
   found!        production       before push

Documentation

Comprehensive documentation can be found in the docs/ folder:

Supported Platforms

Platform	File Pattern	Status
GitHub Actions	`.github/workflows/*.yml`	✅ Full support
GitLab CI	`.gitlab-ci.yml`	✅ Full support
CircleCI	`.circleci/config.yml`	✅ Full support

Installation

From crates.io

cargo install pipechecker

From source

git clone https://github.com/Ayyankhan101/PipeChecker.git
cd PipeChecker
cargo install --path .

Via npm (once published)

npm install -g pipechecker

GitHub Action

PipeChecker can be used directly in your GitHub workflows:

name: CI Pipeline Check
on: [push, pull_request]

jobs:
  pipechecker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Ayyankhan101/PipeCheck/actions/pipecheck@v0.3.0

Action Inputs

Input	Required	Default	Description
`path`	No	`.github/workflows`	Path to workflow file(s)
`strict`	No	`false`	Exit with error on warnings
`diff`	No	`false`	Check only changed files
`diff-branch`	No	`main`	Base branch for diff mode

Diff Mode

Check only workflow files that changed since a base branch:

# Check files changed since main
pipechecker --diff --diff-branch main

# Short form
pipechecker -d

This uses git diff --name-only to find changed workflow files, then checks only those. Faster in monorepos with many workflows.

Quick Start

1. Check a single file

pipechecker .github/workflows/ci.yml

2. Auto-detect your workflow

pipechecker
# ✓ Auto-detected: .github/workflows/ci.yml
# Provider: GitHubActions
# 0 errors, 0 warnings

3. Audit everything

pipechecker --all
# Checking 3 workflow file(s)...
#
# 📄 .github/workflows/ci.yml
#    Provider: GitHubActions
#    ✅ No issues found
#
# 📄 .github/workflows/deploy.yml
#    Provider: GitHubActions
#    1 errors, 2 warnings
#    ❌ ERROR: Circular dependency detected (job: deploy)
#       💡 Remove one of the dependencies to break the cycle
#    ⚠️ WARNING: Job 'deploy' has no steps
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Total: 1 errors, 2 warnings across 3 files

Interactive TUI

PipeChecker includes a terminal UI for browsing results across multiple files:

pipechecker --tui

┌──────────────────────────────────────────┐
│  🔍 Pipecheck - Interactive Mode         │
├──────────────────────────────────────────┤
│  Workflows                               │
│▶ ❌ deploy.yml │ 2 errors │ 1 warnings   │
│  ✅ ci.yml     │ 0 errors │ 0 warnings   │
│  ⚠️  lint.yml   │ 0 errors │ 3 warnings   │
├──────────────────────────────────────────┤
│  [↑/↓] Navigate  [Enter] Details  [Q] Quit│
└──────────────────────────────────────────┘

Keyboard shortcuts:

Key	Action
`↑` / `k`	Move up
`↓` / `j`	Move down
`Enter` / `Space`	Toggle detail view
`q` / `Esc`	Quit

All CLI Flags

Flag	Description
`FILE`	Path to a specific workflow file
`--all`, `-a`	Audit all discovered workflow files
`--tui`	Launch the interactive terminal UI
`--watch`, `-w`	Watch for file changes and re-run audits
`--fix`	Auto-fix issues (pin unpinned actions + Docker `:latest` tags)
`--init`	Initialize a new workflow from a template
`--template`	Template name: `node`, `rust`, `docker`, `gitlab-node`
`--force`	Force overwrite existing files (with `--init`)
`--install-hook`	Install a git pre-commit hook
`--diff`, `-d`	Check only files changed since base branch
`--diff-branch`	Base branch for diff mode (default: `main`)
`--format`, `-f` `<text\|json>`	Output format (default: `text`)
`--strict`, `-s`	Treat warnings as errors (exit code 1)
`--quiet`, `-q`	Only output errors — suppress warnings and info
`--ci`	CI mode — implies `--quiet --strict --format json`
`--verbose`	Show diagnostic info (auditors ran, per-severity counts)
`--explain`	Print detailed explanation for a rule code (e.g. `PC005`)
`--no-pinning`	Skip Docker image and action-pinning checks
`--no-permissions`	Skip permissions auditor (GitHub Actions only)
`--no-schema`	Skip schema validation
`--version`	Show version
`--help`	Show help

Output Explained

Severity Levels

Symbol	Level	Meaning
❌	Error	Must fix — will break your pipeline
⚠️	Warning	Should fix — may cause issues later
ℹ️	Info	Informational — nothing to worry about

Example output with details

Provider: GitHubActions
2 errors, 1 warnings

❌ ERROR: Circular dependency detected (job: deploy) [PC005] [line 42]
   💡 Remove one of the dependencies to break the cycle

❌ ERROR: Job 'deploy' depends on non-existent job 'build' (job: deploy) [PC004] [line 45]
   💡 Add a job with id 'build' or remove the dependency

⚠️ WARNING: Job 'lint' has no steps (job: lint) [PC003] [line 12]
   💡 Add steps to perform work in this job

Each issue includes:

What went wrong (clear message)
Where it happened (job name + line number)
How to fix it (actionable suggestion)

JSON Output

Perfect for CI/CD integration or programmatic consumption:

pipechecker --format json

{
  "provider": "GitHubActions",
  "issues": [
    {
      "severity": "Error",
      "message": "Circular dependency detected: job-a -> job-b -> job-a",
      "location": { "line": 42, "column": 3, "job": "deploy" },
      "suggestion": "Remove one of the dependencies to break the cycle",
      "rule_code": "PC005"
    }
  ],
  "summary": "1 errors, 0 warnings"
}

Modes of Operation

🔧 Auto-Fix Mode

Automatically pins unpinned GitHub Actions to known versions:

pipechecker --fix

🔧 Auto-fix mode

✨ Fixed 2 issue(s) in .github/workflows/ci.yml:

  actions/checkout → actions/checkout@v4
  actions/setup-node → actions/setup-node@v4

💡 Review the changes and commit them!

👀 Watch Mode

Monitors workflow files and re-runs on every save — perfect for development:

pipechecker --watch

👀 Watching for workflow changes...
   Press Ctrl+C to stop

🔄 File changed: .github/workflows/ci.yml
Provider: GitHubActions
0 errors, 0 warnings
✅ All checks passed

🤫 Quiet Mode (CI-Friendly)

Only output errors — suppress warnings and info. Perfect for CI pipelines where you want clean output:

pipechecker --quiet
# or
pipechecker -q

❌ Circular dependency detected (job: deploy) (in .github/workflows/deploy.yml)

Exit code is still 1 if there are errors — works perfectly with --strict for failing CI on any issue.

🤖 CI Mode

One flag that implies --quiet --strict --format json. Ideal for CI automation:

pipechecker --ci

📖 Explain Mode

Get a detailed explanation for any rule code:

pipechecker --explain PC005

📖 Rule PC005 — Circular dependency detected

Two or more jobs form a dependency cycle (A needs B, B needs A).
The pipeline can never start because each job is waiting for another.
Remove one of the edges in the cycle to break it.

Available rule codes:

Code	Rule
`PC001`	Empty pipeline
`PC002`	Duplicate job ID
`PC003`	Empty job steps
`PC004`	Missing dependency
`PC005`	Circular dependency
`PC006`	Hardcoded secret
`PC007`	Secret reference
`PC008`	Undeclared env var
`PC009`	Unpinned action
`PC010`	Docker `:latest` tag
`PC011`	Missing timeout
`PC012`	Missing trigger
`PC013`	Missing `runs-on`
`PC014`	Missing permissions
`PC015`	Invalid YAML
`PC016`	Missing concurrency cancel
`PC017`	Static cache key
`PC018`	Missing artifact retention

📢 Verbose Mode

See exactly what PipeChecker is doing — which files it found, which auditors ran, and per-severity breakdowns:

pipechecker --verbose

📄 Auditing: .github/workflows/ci.yml
🔍 Auditors ran: syntax, dag, secrets, timeout, permissions, schema, concurrency, artifacts, pinning
📊 Found: 0 errors, 1 warnings, 0 info
⏱️  Checked in 3.2ms

⏱️ Timing Metrics

Every audit now shows how long it took — because speed matters:

pipechecker .github/workflows/ci.yml

Provider: GitHubActions
0 errors, 0 warnings
✅ All checks passed
⏱️  Checked in 2.1ms

🔒 Pre-commit Hook

Never commit a broken workflow again:

pipechecker --install-hook

✅ Pre-commit hook installed!
   Pipecheck will run before every commit
   Use 'git commit --no-verify' to skip

The hook automatically validates any workflow files you stage:

$ git commit -m "Update CI pipeline"
🔍 Checking workflows with pipechecker...
❌ ERROR: Circular dependency detected (job: deploy) [line 42]
   💡 Remove one of the dependencies to break the cycle

❌ Workflow validation failed!
Fix errors above or use 'git commit --no-verify' to skip

Configuration File

Create a .pipecheckerrc.yml in your project root to customize behavior:

# Files to skip (glob patterns supported)
ignore:
  - .github/workflows/experimental-*.yml
  - .github/workflows/draft-*.yml
  - old-pipeline.yml

# Toggle individual audit rules
rules:
  circular_dependencies: true   # Detect dependency cycles
  missing_secrets: true         # Flag hardcoded secrets
  docker_latest_tag: true       # Warn about :latest tags
  timeout_validation: true      # Warn about missing timeouts
  permissions_check: true       # Warn about missing permissions
  schema_validation: true       # Structural YAML validation
  concurrency_validation: true  # Check cancel-in-progress
  artifacts_check: true         # Cache/artifact best practices

PipeChecker searches for config in this order:

.pipecheckerrc.yml
.pipecheckerrc.yaml
.pipechecker.yml

How the Auditors Work

📋 Syntax Auditor

Validates the structural integrity of your pipeline:

✅ Jobs are defined
✅ Steps exist within jobs
✅ No duplicate job IDs
✅ needs / depends_on targets exist

🔗 DAG Auditor (Cycle Detection)

Builds a dependency graph of your jobs and runs Tarjan's Strongly Connected Components algorithm:

  job-a ──depends──▶ job-b
    ▲                   │
    │                   ▼
    └────depends──── job-c

→ ❌ Circular dependency detected: job-a → job-b → job-c → job-a

🔒 Secrets Auditor

Scans for security issues in environment variables and run blocks:

env:
  API_KEY: sk_live_abc123         # ⚠️ Hardcoded secret
  TOKEN: ${{ secrets.TOKEN }}     # ✅ Correct way
  RUN: echo ${{ secrets.API_KEY }} # ℹ️ Info — ensure it's configured
  RUN: echo ${{ env.UNDEFINED }}  # ⚠️ Undeclared env var

Detects:

Hardcoded API keys, passwords, tokens
Secret references in with: blocks
Undeclared ${{ env.X }} references
Suspicious values (long alphanumeric strings, base64)

🐳 Docker & 📌 Pinning Auditor

Ensures reproducible builds:

uses: actions/checkout              # ⚠️ No version pin
uses: actions/checkout@v4           # ✅ Pinned
image: nginx:latest                 # ⚠️ Unpredictable
image: nginx:1.25-alpine            # ✅ Specific

⏱️ Timeout Auditor

Warns when jobs lack timeout-minutes — prevents runaway CI jobs:

build:
  runs-on: ubuntu-latest
  # ⚠️ No timeout-minutes — can run forever if something hangs
  steps: [...]

🔐 Permissions Auditor

Warns when GitHub Actions jobs have no explicit permissions: block:

build:
  runs-on: ubuntu-latest
  # ⚠️ No permissions block — inherits write-all token
  steps: [...]

📐 Schema Auditor

Validates YAML structure against provider-specific schemas — catches missing keys, bad types, and structural issues.

🔄 Concurrency Auditor

Checks for cancel-in-progress: true when concurrency groups are used — prevents wasted CI minutes on outdated runs.

📦 Artifacts & Cache Auditor

Checks actions/cache for static keys (should include hashFiles(...)) and actions/upload-artifact for missing retention-days.

Real-World Examples

Example 1: Valid workflow

$ pipechecker .github/workflows/ci.yml
Provider: GitHubActions
0 errors, 0 warnings

Example 2: Circular dependency

jobs:
  deploy:
    needs: [test]
    steps: [{ run: echo deploy }]
  test:
    needs: [deploy]
    steps: [{ run: echo test }]

$ pipechecker broken.yml
Provider: GitHubActions
1 errors, 0 warnings

❌ ERROR: Circular dependency detected (job: deploy)
   💡 Remove one of the dependencies to break the cycle

Example 3: Hardcoded secrets

jobs:
  build:
    env:
      API_SECRET: sk_live_hardcoded_value
    steps: [{ run: echo building }]

$ pipechecker secrets.yml
Provider: GitHubActions
0 errors, 1 warnings

⚠️ WARNING: Job 'build' env 'API_SECRET' may contain a hardcoded secret
   💡 Use secrets.API_SECRET instead of hardcoding

Architecture

pipechecker/
├── src/
│   ├── main.rs          # CLI entry point (clap)
│   ├── lib.rs           # Public API — audit_file, audit_content, discover_workflows
│   ├── models.rs        # Core types — Pipeline, Job, Step, Issue, Severity, rule codes
│   ├── error.rs         # Error enum (thiserror)
│   ├── config.rs        # .pipecheckerrc.yml loading
│   ├── fix.rs           # Auto-fix for action pinning
│   ├── tui.rs           # Interactive terminal UI (ratatui + crossterm)
│   ├── parsers/
│   │   ├── mod.rs       # Provider detection + dispatch
│   │   ├── github.rs    # GitHub Actions YAML parser
│   │   ├── gitlab.rs    # GitLab CI YAML parser
│   │   └── circleci.rs  # CircleCI YAML parser
│   └── auditors/
│       ├── mod.rs       # Module gate
│       ├── syntax.rs    # Structural validation (PC001–PC004)
│       ├── dag.rs       # Dependency graph + cycle detection (PC005)
│       ├── secrets.rs   # Secret/env var scanning (PC006–PC008)
│       ├── timeout.rs   # Missing timeout detection (PC011)
│       ├── permissions.rs # GitHub Actions permissions (PC014)
│       ├── schema.rs    # Structural YAML validation (PC012–PC013, PC015)
│       ├── concurrency.rs # Concurrency group checks (PC016)
│       ├── artifacts.rs # Cache/artifact best practices (PC017–PC018)
│       ├── include.rs   # GitLab include: block parsing
│       └── pinning.rs   # Action/Docker image pinning (PC009–PC010)
├── templates/           # Embedded workflow templates
├── tests/
│   ├── parser_test.rs   # Parser integration tests
│   └── auditors_test.rs # Auditor + fixture tests
└── tests/fixtures/      # Sample workflow files for testing

CI/CD Integration

Add PipeChecker to your own CI pipeline:

# Option 1: Use the GitHub Action
- uses: Ayyankhan101/PipeCheck/actions/pipecheck@v0.3.0

# Option 2: Run directly
- name: Validate workflows
  run: |
    cargo install pipechecker
    pipechecker --ci

Or use it as a pre-commit hook (recommended):

pipechecker --install-hook

Development

Run tests

cargo test
# 134 tests — all passing

Lint & format

cargo clippy -- -D warnings
cargo fmt -- --check

Coverage

cargo tarpaulin --fail-under 55

License

This project is licensed under either MIT or Apache-2.0 at your option.

SPDX: MIT OR Apache-2.0

PipeChecker — because waiting 10 minutes for CI to tell you about a typo is nobody's idea of fun.

Report a bug · Request a feature · Contributing

pipechecker 0.3.1