# PushCI

[![npm version](https://img.shields.io/npm/v/pushci.svg)](https://www.npmjs.com/package/pushci)
[![npm downloads](https://img.shields.io/npm/dm/pushci.svg)](https://www.npmjs.com/package/pushci)
[![License: BUSL-1.1](https://img.shields.io/badge/License-BUSL--1.1-blue.svg)](LICENSE)
[![Release](https://img.shields.io/github/v/release/finsavvyai/pushci-cli)](https://github.com/finsavvyai/pushci-cli/releases/latest)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://pushci.dev/ai)

## AI agents write the code. PushCI proves it is safe to ship.

PushCI is an **independent delivery verification and promotion control plane for AI-written changes**. It issues signed proof tied to exact source, required checks, actor, immutable artifact, environment, database state, and policy before production.

The CLI is the human/native automation interface. MCP-compatible agents such as Claude Code, Cursor, Copilot, and Codex use the same governed primitives. PushCI can run work, but the independent receipt—not the executor's own green flag—is the admission record.

PushCI runs beside existing GitHub Actions, GitLab CI, Buildkite, Jenkins, and provider delivery systems. Local, self-hosted, or customer-owned compute is the default; optional managed execution is capacity-capped, budgeted, and separately metered.

```bash
npm install -g pushci
pushci init
pushci verify --local
pushci verify --publish  # authenticated, project-bound, server-signed receipt
```

Or expose the same delivery runtime to an AI agent:

```json
{
  "mcpServers": {
    "pushci": {
      "command": "pushci",
      "args": ["mcp"]
    }
  }
}
```

## One independent proof across every executor

```text
Developer / coding agent
          │
          ├── existing CI or customer-owned runner
          └── optional managed execution
                      │
                      ▼
             PushCI verification gate
                      ├── exact source / PR HEAD
                      ├── required checks and actor
                      ├── artifact digest
                      ├── environment / database state
                      └── policy and approval
                                   │
                                   ▼
                         signed receipt → promotion
```

The coding agent may be the author and any CI may be the executor. PushCI remains the independent judge of whether the exact change is eligible to move.

## Why PushCI

Traditional CI assumes every change should begin by renting a clean remote machine. AI agents also tend to fall back to ad-hoc shell commands and provider-specific scripts when they need to deploy infrastructure. PushCI starts with a different model: **use the compute and delivery knowledge already available locally, expose it through one agent-friendly interface, and escalate to controlled infrastructure only when required.**

```text
Existing repository / CI
          │
          ▼
      PushCI init
          │
          ├── detect stack and workflow
          ├── preserve/migrate existing CI
          ▼
Developer or AI agent
          │
          ▼
   Local / self-hosted execution
          │
          ├── build
          ├── test
          ├── scan
          └── migration analysis
          │
          ▼
     immutable artifact
          │
          ▼
   provision / preview / staging
          │
          ▼
       verification
          │
          ▼
      safe promotion
```

PushCI is deliberately **local-first, not local-only**. Fast validation can run on the developer machine; teams can use self-hosted runner pools and optional managed execution. Existing GitHub Actions, GitLab CI, Jenkins, Buildkite, and other delivery systems can remain in place while workloads migrate incrementally.

## Core value

### Agent-native delivery

The CLI and MCP server expose the delivery lifecycle as callable capabilities. An agent can inspect a repository, initialize/migrate its pipeline, run tests, diagnose failures, manage secrets, provision supported infrastructure, create preview environments, deploy, and request verification without learning each provider's bespoke operational interface.

This is the strategic agent loop:

```text
agent writes code
    ↓
pushci build / run
    ↓
failure → structured diagnosis → repair
    ↓
pushci provision / preview
    ↓
integration verification
    ↓
pushci deploy / promote
    ↓
receipt + audit trail
```

The long-term goal is **bounded autonomy**: agents can move software forward quickly, while PushCI supplies policy, credentials boundaries, environment isolation, artifact lineage, and verification evidence.

### Use the compute you already own

Keep install, lint, unit tests, builds, scans, and other cache-friendly work local when policy allows it. Remote infrastructure is reserved for stages that actually require cloud bindings, shared services, controlled builders, or realistic environments.

### Migrate without a platform rewrite

`pushci init` detects stack and existing CI intent. The target experience is side-by-side adoption: run PushCI locally, prove the feedback/cost benefit, then migrate selected expensive stages when the team is ready. This also gives agents a normalized interface over legacy delivery systems rather than requiring them to rewrite everything first.

### Build once, promote the verified artifact

Where the deployment target supports immutable artifacts, PushCI's direction is build-once/promote-everywhere. Preview, staging, and production should refer to the same artifact digest rather than silently rebuilding different binaries at every step.

### Verify realistic environments

PushCI includes preview-environment lifecycle capabilities. Preview and staging can become structured verification evidence including provider/target identity, database isolation, migration state, configuration/binding fingerprints, health checks, and the exact artifact deployed.

### Govern human and AI-generated changes

Humans and agents use the same delivery primitives but can receive different policy. PushCI can record actor/provenance when available, apply stricter requirements to autonomous changes, and preserve an audit trail of what an agent actually built, provisioned, changed, and deployed.

## Quick start

```bash
npm install -g pushci
pushci init
pushci verify
```

Other install options:

```bash
brew install finsavvyai/tap/pushci
curl -fsSL https://pushci.dev/install.sh | sh
```

Useful commands:

```text
pushci init          detect the stack and configure/migrate validation
pushci verify        verify the current change and produce evidence
pushci run           execute the pipeline directly
pushci preview       manage realistic preview environments
pushci migrate       migrate an existing GitHub Actions workflow
pushci deploy        validate and execute deployments
pushci troubleshoot  diagnose failures with actionable fixes
pushci index         build the dependency graph / blast-radius model
pushci mcp           expose PushCI delivery capabilities to AI coding agents
pushci mcp configure hermes  install a governed Hermes delivery operator
pushci agent         run PushCI agent workflows
pushci runner        manage execution capacity
```

## AI-agent integration

PushCI includes an MCP server for coding agents such as Claude Code, Cursor, Windsurf, Cline, and other MCP-compatible clients.

```json
{
  "mcpServers": {
    "pushci": {
      "command": "pushci",
      "args": ["mcp"]
    }
  }
}
```

Available MCP capabilities include stack detection, pipeline initialization, pipeline execution, status, environment diagnosis, secret management, security scanning, migration recommendations, healing/diagnosis, and agent workflows. The product direction is to expose provisioning, preview, verification, and promotion through the same governed agent interface wherever the underlying PushCI capability is already available and safe to expose.

## Verification model

The core product primitive is a software-change **verification**. A verification binds evidence not only to code, but to the delivery path an agent or developer executed: exact repository/commit and dirty-tree state, actor, checks, artifact, environment, migration state, policy, savings, and results.

Receipts have deterministic local identities and tamper-checked history. `pushci verify --publish` sends a completed receipt to the authenticated project, where the control plane independently recomputes its evidence hash, stores an audited ledger row, and returns a project-bound ECDSA P-256 attestation. In the immutable image-promotion path, artifact passports embed that receipt and production requires the exact published attestation. GitHub repositories can also receive one `PushCI / Verification` Check Run bound to the live PR HEAD; a new HEAD immediately makes the prior receipt ineligible. Locally asserted agent metadata remains distinguishable from provider-verified provenance.

## Documentation

- [CLI reference](docs/CLI.md)
- [Model Context Protocol guide](docs/MCP.md)
- [Verification evidence](docs/VERIFICATION_EVIDENCE.md)
- [Verification marketing claim matrix](docs/VERIFICATION_MARKETING_CLAIM_MATRIX.md)
- [AI-agent integration](https://pushci.dev/ai)
- [pushci.yml guide](https://pushci.dev/docs/pushci-yaml)
- [Build roadmap](ROADMAP.md)
- [GitHub App and verification implementation plan](.planning/github-app-verification-plan.md)
- [Product refinement opportunities](.planning/product-refinement-opportunities.md)

## License

PushCI is licensed under BUSL-1.1. See [LICENSE](LICENSE).