# No-Mistakes Pipeline Steps: Complete Guide to Built-in Checks and Customization

> Master no-mistakes pipeline steps with over 15 built-in checks for automated PR validation. Customize your workflow easily using the .no-mistakes.yaml file.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: deep-dive
- Published: 2026-06-27

---

**The no-mistakes pipeline automates PR validation through 15+ built-in steps—including Intent, Lint, Document, Evidence, CI, Rebase, and PR creation—each customizable via the [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) configuration file.**

The `kunchenguid/no-mistakes` repository implements a fully automated CI pipeline that validates, fixes, and merges pull requests through a deterministic sequence of **no-mistakes pipeline steps**. Each step implements the `pipeline.Step` interface defined in [`internal/pipeline/pipeline.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/pipeline.go) and is orchestrated by the executor in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go). All behavior is controlled through the repository-wide [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) configuration file, parsed by [`internal/config/config.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/config.go).

## Built-in No-Mistakes Pipeline Steps

The pipeline consists of specialized steps located under `internal/pipeline/steps`. The executor invokes these in a deterministic order, with each step capable of returning `SkipRemaining` to halt further processing.

### Validation and Analysis Steps

These steps inspect code quality, intent, and documentation coverage before allowing the pipeline to proceed.

**Intent** (`StepIntent`) – Extracts the high-level intent of the PR (e.g., "add feature", "fix bug") and validates the user-provided description against the actual code changes. Implementation lives in [`internal/pipeline/steps/intent.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/intent.go).

**Lint** (`StepLint`) – Executes the configured linter (default: `golangci-lint`) and surfaces style or static-analysis findings. Source file: [`internal/pipeline/steps/lint.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/lint.go).

**Document** (`StepDocument`) – Ensures code changes are reflected in documentation files (e.g., [`README.md`](https://github.com/kunchenguid/no-mistakes/blob/main/README.md) or `docs/`), utilizing the document agent when gaps are detected. Found in [`internal/pipeline/steps/document.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/document.go).

**Evidence** (`StepEvidence`) – Collects supporting artifacts such as screenshots or test logs, attaching them to PR comments for reviewer visibility. Implementation: [`internal/pipeline/steps/evidence.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/evidence.go).

### Integration and CI Steps

These steps handle external platform integration and continuous execution environments.

**CI – GitHub** (`StepCI`) – Executes repository-defined CI checks including tests and static analysis, with automatic fixing capabilities when enabled. Located in [`internal/pipeline/steps/ci.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci.go).

**CI – GitLab** (`StepCIGitLab`) – Mirrors the GitHub CI functionality using GitLab APIs and webhooks. Source: [`internal/pipeline/steps/ci_gitlab.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_gitlab.go).

**CI – Bitbucket** (`StepCIBitbucket`) – Provides CI integration for Bitbucket pipelines. Found in [`internal/pipeline/steps/ci_bitbucket.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_bitbucket.go).

**Shell** (`StepShell`) – Runs user-specified shell commands defined under `commands.test`, `commands.lint`, or similar keys in a controlled subprocess environment. Implementation: [`internal/pipeline/steps/shell.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/shell.go).

**Demo** (`StepDemo`) – Optionally runs live demonstrations (e.g., spinning up containers) to verify end-to-end functionality. Located in [`internal/pipeline/steps/demo.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/demo.go).

### Git Workflow Steps

These steps manage branch synchronization and push safety.

**Rebase** (`StepRebase`) – Rebases the feature branch onto the latest remote default branch, handling force-push detection, bundled-default-branch detection, and conflict resolution via the agent. Source: [`internal/pipeline/steps/rebase.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/rebase.go).

**Force-Push Safety** (`StepForcePush`) – Determines whether `git push --force-with-lease` is safe based on remote-branch state and patch-ID comparison. Implementation: [`internal/pipeline/steps/forcepush.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/forcepush.go).

**Push** (`StepPush`) – Pushes the rebased branch back to the remote, utilizing the lease decision from the Force-Push Safety step. Found in [`internal/pipeline/steps/push.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/push.go).

### PR Management Steps

These steps handle pull request creation and human-in-the-loop review processes.

**PR** (`StepPR`) – Creates or updates the pull request on the configured platform (GitHub, GitLab, or Bitbucket). Source: [`internal/pipeline/steps/pr.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/pr.go).

**PR-Summary** (`StepPRSummary`) – Generates a concise summary of the PR including title, description, findings, and review status, posting it as a comment. Implementation: [`internal/pipeline/steps/prsummary.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/prsummary.go).

**Review** (`StepReview`) – When auto-fix is disabled, pauses the pipeline to present findings to a human reviewer and waits for approval or rejection. Found in [`internal/pipeline/steps/review.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/review.go).

## How to Customize No-Mistakes Pipeline Steps

All customization flows through [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) at the repository root, which is merged with defaults defined in [`internal/config/defaults.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/config/defaults.go).

### Configuration via .no-mistakes.yaml

The configuration file supports granular control over step behavior:

```yaml
commands:
  test: "go test -race ./..."
  lint: "golangci-lint run ./..."

auto_fix:
  review: 1
  ci: 0

ci_timeout: "30d"

intent:
  prompt: "You are reviewing a feature addition…"

review:
  template: "Please check the following…"

push:
  force: true

pr:
  draft: true
  labels: ["automerge"]

```

### Disabling and Skipping Steps

Remove the corresponding configuration entry to skip a step. For example, omit `commands.lint` to disable the **Lint** step, or set `auto_fix.ci: 0` to require manual approval for CI failures.

Use the CLI flag `--skip-steps` for temporary per-run suppression:

```bash
no-mistakes run --skip-steps=document,evidence

```

### Adding Custom Shell Commands

The **Shell** step executes arbitrary commands defined under the `commands` key. The findings are automatically fed into the **Review** gate.

```yaml
commands:
  security-scan: "gosec ./..."
  benchmark: "go test -bench=. ./..."

```

### Runtime Overrides with CLI Flags

The CLI accepts `--set <key>=<value>` flags parsed by [`internal/cli/flags.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/cli/flags.go) to override YAML values for a single execution:

```bash
no-mistakes run --set intent.prompt="You are reviewing a security patch…" \
                --set ci_timeout="7d"

```

### Extending with Custom Step Implementations

To add a custom step, implement the `pipeline.Step` interface using helpers from [`internal/pipeline/steps/common.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/common.go), then register the step in `pipeline.NewExecutor`. Expose configuration knobs under a top-level key (e.g., `my_step:`) and read them via `cfg.Get("my_step.some_option")`.

## Summary

- **No-mistakes pipeline steps** include 15+ built-in implementations covering validation (Intent, Lint, Document), CI integration (GitHub, GitLab, Bitbucket), Git workflow (Rebase, Force-Push, Push), and PR management (PR, PR-Summary, Review).
- Each step implements the `pipeline.Step` interface and is orchestrated by [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go).
- All customization happens through [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml), supporting command overrides, auto-fix toggles, timeouts, and PR metadata.
- Steps can be disabled by removing configuration entries or using `--skip-steps` flags.
- Custom steps require implementing the interface and registering in `pipeline.NewExecutor`.

## Frequently Asked Questions

### How do I disable the automatic linting step in the no-mistakes pipeline?

Remove the `commands.lint` entry from your [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml) file, or set `auto_fix.lint: 0` to require manual approval. Alternatively, use the `--skip-steps=lint` CLI flag to suppress it for a single run.

### What is the difference between the Force-Push Safety and Push steps?

The **Force-Push Safety** step (`StepForcePush`) analyzes remote-branch state and patch-IDs to determine if `--force-with-lease` is safe, while the **Push** step (`StepPush`) executes the actual push command using that safety determination. They work sequentially to prevent accidental overwrites.

### Can I add custom validation steps without modifying the Go source code?

For simple validations, use the **Shell** step by adding commands under `commands.*` in [`.no-mistakes.yaml`](https://github.com/kunchenguid/no-mistakes/blob/main/.no-mistakes.yaml). For complex logic requiring state management or custom interfaces, you must implement the `pipeline.Step` interface in Go and register it in [`internal/pipeline/executor.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/executor.go), as shown in [`internal/pipeline/steps/common.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/common.go).

### How does the CI step handle platform differences between GitHub, GitLab, and Bitbucket?

The pipeline provides three separate implementations: `StepCI` for GitHub ([`internal/pipeline/steps/ci.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci.go)), `StepCIGitLab` ([`internal/pipeline/steps/ci_gitlab.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_gitlab.go)), and `StepCIBitbucket` ([`internal/pipeline/steps/ci_bitbucket.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/steps/ci_bitbucket.go)). Each uses platform-specific APIs and hooks, but presents a unified interface to the executor and supports the same `ci_timeout` and `auto_fix` configuration options.