willlzl/Perpetual

The self-evolving CI/CD pipeline and testing platform.

Repair broken builds, create test environments from your app, and make business journeys part of every release.

Demo · Vision · Quickstart · Docs · Roadmap · Discussions

Watch the walkthrough · 2 min 56 sec

Recorded in a simulated demo environment. Production deployment is a preview; see Status for what is available today.

Shipping a change means more than writing the code. Someone still has to repair the build, prepare a test environment, check that the feature works, and make sure existing user journeys still work too. As a product grows, that work grows with it.

A green build can still ship a broken checkout. Tests with fixed mock responses can miss failures across authentication, billing and application state. Manual testing catches some of those gaps, but makes every release depend on someone repeating the same work.

Testing belongs inside the delivery pipeline. Its results should decide whether a change moves forward.

Perpetual brings build repair, test environments, business testing and promotion gates into one workflow. It works with GitHub Actions and your existing deployment workflows, connecting the question “does it build?” to “does the product still work for its users?”

The goal is a pipeline that can recover from failures, reduce delivery time, and keep its tests useful as the product changes. The 0.1 alpha starts with build repair and business-journey gates.

See the roadmap for the next implementation steps.

flowchart LR
  push["Push to your target branch"] --> twin["Rebuild the stage's twin"]
  twin --> journeys["Run approved business journeys"]
  journeys --> gate["Report the GitHub status"]
  gate --> promotion["Promote or block the commit"]

1. Connect your repository and branch. Perpetual shows your GitHub Actions workflows and configured deployment targets in one pipeline.
2. Create a Beta environment. Perpetual builds a Docker Compose twin from your application's code, with stateful dependencies, fixtures and test accounts. Add another Sandbox stage, such as Gamma, when you need another gate.
3. Discover and review business journeys. An agent explores the running app and drafts complete scenarios. You can add your own cases and edit their goals, prerequisites and expected outcomes. For example: sign in → create a workflow → save and reopen it → run it → see the result and credits deducted.
4. Turn those journeys into a release gate. Generate, verify and approve their Playwright code. On each new push to the target branch, Perpetual rebuilds the twin at that commit and runs the approved tests. Watch the browser live and inspect the recordings afterward. A failed journey blocks promotion; a blocked or needs-review result requires a manual release; a pass advances to the next Sandbox stage.
5. Repair failed builds through a PR. For eligible build failures, an agent works in an isolated Docker repair box and opens a fix. Build's Autopilot can merge after CI and every configured Sandbox journey gate pass at the exact PR head, provided no change rule holds it. Choose Ask first to keep the merge decision with you.

Perpetual waits for the commit's reported GitHub Actions builds before running Sandbox gates, then posts a perpetual/<Stage> GitHub commit status. Require it when promoting into a protected release branch, or have your deployment workflow check it. The optional Deploy action requests the tested commit through a repository-owned GitHub deployment handler and follows its real status. Gate configuration → · Deployment setup and limits →

A twin runs your application's actual code against working services with test data. A journey keeps its session and business state across steps, so it can exercise the interaction between your UI, backend and dependencies.

Official local modes and sandboxes come first. Where a vendor has none, Perpetual uses vercel-labs/emulate. It records each dependency's source on the environment; an unsupported integration or missing test account stays an explicit blocker.

Twins use test credentials and fixtures, not copies of production customer data. A working environment alone is never a passing test: the journey's reviewed checks must observe its business outcome. Twin setup and supported services →

You need Node.js 24.12+, Docker for build repair and Docker Desktop for twins (twins do not work on a native Linux engine), the GitHub CLI, and uv. Setup installs the project dependencies, interface, Chromium and browser runtime, and reports missing prerequisites.

git clone https://github.com/willlzl/Perpetual.git && cd Perpetual
npm run setup
node src/cli.ts serve --repo /path/to/your/app

Serving opens the link it prints, http://127.0.0.1:4317/#secret=…, in your default browser and signs it in. If the browser cannot be opened, open that printed link yourself. Use --no-open for a headless session. In another browser, open the printed link or paste it into Launch link on the connection page and choose Connect:

1. Settings: add an OpenRouter API key.
2. Connect GitHub and choose the repository and target branch. The gate watches repositories chosen this way.
3. Add Beta, choose Create Beta environment, and connect any requested test services or accounts.
4. Review the drafted journeys, then Generate code, Verify code and Approve code. Approval requires three passing runs and a control run whose blocked writes cause a reviewed check to fail.
5. Push a new commit to the target branch while the controller is running. Use its perpetual/Beta status to gate release-branch promotion or deployment.

To update Perpetual, run git pull and then npm run setup again in the clone before restarting it: serve serves the interface as setup last built it.

Set up Perpetual (https://github.com/willlzl/Perpetual) for this repository: clone it outside this repository, run `npm run setup` in the clone and install anything it reports missing, then follow the clone's docs/onboarding.md with me, asking me its questions one at a time. Leave this repository unchanged, and ask me before you enter an API key or sign in anywhere.

• You review the tests. AI writes twin configurations, drafts journeys and code, and proposes build repairs. Only reviewed journeys with approved code run automatically in the gate.
• Approved tests replay without an agent. Runs execute approved Playwright code with independent browser checks and no automatic retries. API and database checks are planned. Test execution uses no model; AI features inside your application can still use one.
• You control the environment. The controller binds to localhost and polls GitHub while running. Hosted twins, a GitHub App and webhooks are not available yet. The desktop sandbox is experimental.
• Deployment needs a configured handler. Manual deployment requests are available through GitHub; your workflow deploys the exact tested commit and reports the result. This channel still needs end-to-end cloud acceptance. Existing provider autodeploy must be gated separately.
• The full vision is still being built. Pipeline optimization, dependency upgrades, test-code repair, automatic deployment after gates and production rollback are planned.

Journey approval and verification → · Build repair and its limits → · Changelog →

I started Perpetual after 4+ years as a software engineer at Amazon and more than 20 freelance projects. I kept spending time maintaining delivery pipelines, fixing failed builds, preparing test environments and manually checking releases.

One production incident made the gap clear: mocked integration tests missed a broken business scenario, and getting the fix through the pipeline took hours. In my freelance work, skipping pipeline setup simply moved that effort into manual checks before every release.

Perpetual's goal is to make a reliable delivery pipeline practical to set up and keep running as a product grows.

• Pipeline: the stages, Build and Production, branches and the Git graph
• Twins: how a twin is built and which services it supports
• Journeys: discovery, review, journey code and its verification, runs and recordings
• CI/CD gate: commit statuses, release and branch protection
• Build repair: the agent's box, its change rules, the pull request, the journey gates at its head and the merge
• Providers: GitHub, Vercel and Railway connections
• Connectors: local Better Auth by default for Slack, Linear and Jira, optional broker routing for Slack/Linear/Jira, and Gmail through the local Composio broker trial
• CLI and the experimental desktop sandbox
• Architecture, decision records and the glossary

Run the current open-source alpha on your own machine under the AGPL. A hosted version with subscription and usage-based pricing is planned.

• Discussions for questions and ideas
• Issues for bugs
• SECURITY.md for reporting vulnerabilities privately

Contributions are welcome; start with CONTRIBUTING.md and the good first issue label. First-time contributors sign the CLA once by commenting on their pull request. Coding agents should read AGENTS.md.

Perpetual is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).

• Running Perpetual unmodified, on your machine, in your CI or inside your organization, requires nothing further.
• If you modify Perpetual and let users interact with your modified version over a network, such as a hosted service, you must offer those users its complete corresponding source under the same license (section 13).
• The Perpetual name and logos are not licensed under the AGPL; see TRADEMARKS.md. Third-party components keep their own licenses; see docs/ASSETS.md and NOTICE.