Diffinery

codician/diffinerypublic

Open-source, agent-first GitHub and GitHub Actions alternative that runs on your own Cloudflare account: git hosting, pull requests, code review and drop-in GitHub Actions YAML on Workers, Durable Objects, R2 and Containers.

2a04c7b

Branches

claude/early-access-cta claude/github-discoverability claude/readme-reorganize claude/readme-screenshots-up claude/showcase-agents-plugins lists-archived main marketplace-builds mcp-registry-auth mcp-registry-docs plugins-any-instance privacy-page

Tags

v0.1.0
diffinery/README.md
155 lines · 13.6 KB
PreviewCode
Raw History
1# Diffinery
2
3**An open-source, self-hostable git forge with GitHub Actions–compatible CI, built for teams of people and AI agents, running entirely on Cloudflare.**
4
5[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
6[![Docs](https://img.shields.io/badge/docs-diffinery.com%2Fdocs-f38020.svg)](https://diffinery.com/docs)
7[![Runs on Cloudflare](https://img.shields.io/badge/runs%20on-Cloudflare%20Workers-f38020.svg)](https://diffinery.com/built-on-cloudflare)
8
9Diffinery hosts Git repositories, pull requests with reviews and a merge queue, issues, releases and a container registry, and runs your existing `.github/workflows/*.yml` files as they are. AI agents get accounts of their own, with guardrails the server enforces, and work through MCP, the REST API, git or the CLI. Everything runs on Cloudflare: Workers, Durable Objects, D1, R2, Queues, Workflows and Containers. There are no servers to run, and you can deploy your own instance to your own Cloudflare account.
10
11- **Website and public instance:** [diffinery.com](https://diffinery.com)
12- **Documentation:** [diffinery.com/docs](https://diffinery.com/docs) ([llms.txt](https://diffinery.com/llms.txt) for AI assistants)
13- **Source:** [diffinery.com/codician/diffinery](https://diffinery.com/codician/diffinery), where development happens. [github.com/codician-team/diffinery](https://github.com/codician-team/diffinery) is a mirror of it.
14
15## Contents
16
17- [Why Diffinery](#why-diffinery)
18- [Features](#features)
19- [Self-host on your own Cloudflare account](#self-host-on-your-own-cloudflare-account)
20- [How it runs on Cloudflare](#how-it-runs-on-cloudflare)
21- [Develop locally](#develop-locally)
22- [Repository layout](#repository-layout)
23- [What Diffinery doesn't do (yet)](#what-diffinery-doesnt-do-yet)
24- [FAQ](#faq)
25- [Contributing, security and license](#contributing-security-and-license)
26
27## Why Diffinery
28
29- **Git hosting, pull requests and CI in one serverless app.** One Cloudflare Worker serves the web UI, git over HTTPS, a GitHub-compatible REST and GraphQL API, and an MCP server. Each repository is its own Durable Object with its own SQLite database, so repositories scale out instead of sharing one database server.
30- **Your GitHub Actions workflows run unchanged.** The same triggers, expressions, matrices, `needs`, outputs, reusable workflows, environments, secrets, variables, OIDC, service containers and Docker. Marketplace actions (`uses: owner/repo@ref`) are downloaded and run. Every known difference is listed in [Compatibility with GitHub Actions](https://diffinery.com/docs/actions/compatibility).
31- **Runners that exist only while a job runs.** Each job gets a fresh Ubuntu 24.04 container on Cloudflare Containers, billed by Cloudflare only while it runs. The default size has 4 vCPUs and 12 GiB of memory, and jobs that use little of it move to smaller sizes on their own. Self-hosted runners cover macOS, Windows, Arm and GPUs.
32- **Built for AI agents, with a human in the loop.** Agents are first-class accounts owned by a person or an organization, with their own tokens and limits. They can't push or merge to protected branches unless a rule allows it, their pull requests need a human approval, and every commit they make records who they act for. Agent tasks run Claude Code, Codex or your own command in a sandbox and open a pull request.
33- **Secure by default.** Passkey sign-in with no passwords, invite-only accounts, branch protection, push protection that blocks leaked credentials, envelope-encrypted secrets, kill switches and an append-only audit log.
34- **Moving from GitHub is one step.** A server-side importer brings a repository or a whole organization over with its history, issues, pull requests, reviews and releases, and `gh`, Octokit, VS Code and JetBrains IDEs work against Diffinery.
35
36## Features
37
38| Area | What you get | Docs |
39| --- | --- | --- |
40| Git | Clone, fetch and push over HTTPS with a token; shallow clones, Git LFS, `refs/pull/<n>/head` and `/merge`; large pushes unpacked from R2 in pieces | [Git over HTTPS](https://diffinery.com/docs/repositories/git) |
41| Pull requests | Draft PRs, reviews with line comments, required approvals and checks, merge, squash and rebase, auto-merge, a merge queue with `merge_group` runs, and an `intent` field that tells reviewers what a change is for | [Pull requests](https://diffinery.com/docs/collaboration/pull-requests) |
42| Issues and releases | Issues, labels, milestones, reactions, mentions, releases with assets and generated notes | [Collaboration](https://diffinery.com/docs/collaboration/issues) |
43| Actions (CI/CD) | GitHub Actions–compatible workflows on hosted runners in Cloudflare Containers or self-hosted runners; caches, artifacts, secrets, environments, OIDC, Docker, service containers, concurrency groups, scheduled runs | [Actions overview](https://diffinery.com/docs/actions/overview) |
44| Container registry | Push and pull OCI images at `<your host>/<owner>/<name>`, in place of ghcr.io | [Container registry](https://diffinery.com/docs/packages/container-registry) |
45| Agents | Agent accounts and tokens, an MCP server at `/mcp`, sandboxes, agent tasks, agent code review, projects with shared memory, and a Today page of what needs you | [Agents](https://diffinery.com/docs/agents/overview) |
46| API and tools | GitHub-compatible REST (`/api/v3`) and GraphQL (`/api/graphql`) APIs, webhooks, the `diffinery` CLI, `gh` support, VS Code and JetBrains plugins, a Claude Code and Codex plugin (in [`plugins/`](plugins)) | [REST API](https://diffinery.com/docs/reference/rest-api) |
47| Security | Passkeys (WebAuthn), branch protection, push protection, encrypted secrets, audit log, moderation, rate limits, quotas and kill switches | [Security overview](https://diffinery.com/docs/security/overview) |
48| Migration | Import from GitHub with history, issues, pull requests, reviews and releases, from the web, CLI, API or MCP | [Migrate from GitHub](https://diffinery.com/docs/migrate-from-github) |
49
50## Self-host on your own Cloudflare account
51
52Diffinery is designed to be deployed by anyone to their own Cloudflare account and domain. Nobody who uses your instance needs a Cloudflare account; only the deployment does.
53
54**You need:**
55
56- A Cloudflare account on the **Workers Paid** plan, with R2 enabled. Containers, Durable Objects with SQLite, Workflows and Queues need the paid plan.
57- A domain on that account (Diffinery is served at the root of a hostname such as `git.example.com`).
58- A Cloudflare API token with the permissions listed in [Deploy your own Diffinery](https://diffinery.com/docs/self-hosting/deploy#step-2-create-a-cloudflare-api-token).
59- Node.js 22, pnpm 10, Docker, `jq`, `curl` and `openssl` on the machine you deploy from.
60
61**Deploy:**
62
63```sh
64git clone https://diffinery.com/codician/diffinery.git # or the GitHub mirror
65cd diffinery
66
67export CLOUDFLARE_API_TOKEN=... # never commit it
68export CLOUDFLARE_ACCOUNT_ID=...
69export DIFFINERY_DOMAIN=git.example.com # your hostname
70export BOOTSTRAP_ADMINS=you@example.com # who becomes site administrator on first sign-in
71
72scripts/setup.sh --dry-run # checks tools, token and config without changing anything
73scripts/setup.sh # creates the Cloudflare resources and deploys
74```
75
76The setup script creates whatever is missing in your account (the D1 database, R2 bucket and lifecycle rules, queues, a Turnstile widget and a Cloudflare Access application for email recovery), applies the database migrations, deploys the Worker and the runner image, generates the Worker's own secrets once, and checks that the site answers. Every step is safe to repeat, so the same command updates an existing instance. Then open `https://<your host>/auth/access`, confirm your email with the one-time code and add a passkey: you are the first administrator.
77
78You can also deploy from CI with the included [Deploy workflow](.github/workflows/deploy.yml) on Diffinery or GitHub Actions. The full guide, including email sending, DNS, Access and troubleshooting, is [Deploy your own Diffinery](https://diffinery.com/docs/self-hosting/deploy), and every setting is described in [Configuration](https://diffinery.com/docs/self-hosting/configuration).
79
80## How it runs on Cloudflare
81
82| Piece | Cloudflare product |
83| --- | --- |
84| Web UI, git smart HTTP, REST and GraphQL APIs, MCP | Workers ([Hono](https://hono.dev)) |
85| One repository: refs, objects, pull requests, issues, reviews, checks, runs | A Durable Object with SQLite (`RepoDO`), one per repository |
86| Large objects, Git LFS, container images, logs, caches, artifacts | R2 |
87| Accounts, organizations, tokens, invites, notifications, audit log | D1, read through the Sessions API for read replicas |
88| Webhooks, notifications, email | Queues, with dead-letter queues, and Email Sending |
89| Workflow runs (durable, survive restarts, 6-hour job timeout) | Workflows |
90| Job runners, agent sandboxes and import transfers | Containers (an Ubuntu 24.04 image in `containers/runner`) |
91| Scheduled workflows (`on: schedule`) | Cron Triggers |
92| Live logs and pull request updates | Durable Object WebSockets with hibernation |
93| Sign-in | Passkeys (WebAuthn); Cloudflare Access guards only `/auth/access`, the email recovery path |
94
95More in [Architecture](https://diffinery.com/docs/self-hosting/architecture).
96
97## Develop locally
98
99```sh
100pnpm install
101pnpm -r build && pnpm -r typecheck && pnpm -r test
102pnpm --filter @diffinery/app db:migrate:local
103pnpm dev # http://localhost:8787, signed in as dev@diffinery.local
104pnpm --filter @diffinery/app e2e # wrangler dev, real git, the runner agent and Chromium
105```
106
107`pnpm dev` runs the Worker under `wrangler dev` with local D1, R2 and queues, so you need no Cloudflare account to work on Diffinery. The end-to-end suite pushes real repositories with `git`, runs their workflows through the real runner agent, drives the MCP server and the REST API (with `@octokit/rest`), and signs in with passkeys in Chromium. See [CONTRIBUTING.md](CONTRIBUTING.md).
108
109## Repository layout
110
111```
112apps/diffinery the Worker: web UI, git, REST/GraphQL, MCP, Actions, D1 migrations, docs, e2e tests
113apps/cli the `diffinery` command-line client
114apps/vscode the VS Code, Cursor and Windsurf extension
115apps/jetbrains the JetBrains IDE plugin
116plugins the Claude Code and Codex plugins (marketplaces in .claude-plugin/ and .agents/plugins/)
117containers/runner the runner agent, sandbox server and the container image
118packages/git-core git objects, packfiles, deltas, diff and merge, in pure TypeScript
119packages/workflow-yaml the GitHub Actions workflow parser, expressions, matrices and cron
120packages/shared types shared by the Worker and the runner
121scripts setup, bootstrap and deploy scripts for Cloudflare
122```
123
124## What Diffinery doesn't do (yet)
125
126Diffinery is honest about its gaps. Today it has no hosted macOS, Windows or Arm runners (use self-hosted runners), no forks, no app marketplace, and nothing like Codespaces, Pages or Discussions. Some GitHub events, such as `issues` and `issue_comment`, are accepted in workflows but never start a run. The full list is in [Compatibility with GitHub Actions](https://diffinery.com/docs/actions/compatibility) and [Diffinery vs GitHub](https://diffinery.com/compare/github).
127
128## FAQ
129
130**What is Diffinery?**
131An open-source git forge and CI platform that runs entirely on Cloudflare. It replaces GitHub's code hosting, pull requests and GitHub Actions in one app that you can self-host on your own Cloudflare account.
132
133**Is Diffinery a self-hosted GitHub alternative?**
134Yes. Like Gitea, Forgejo or GitLab, you can run it yourself, but instead of a server or a Kubernetes cluster it deploys to Cloudflare's serverless platform, and its CI runs GitHub Actions workflow files instead of a format of its own.
135
136**Do my GitHub Actions workflows run without changes?**
137Most do. Diffinery reads `.github/workflows/*.yml` with the same syntax and runs marketplace actions. Jobs that need hosted macOS, Windows or Arm runners need a self-hosted runner. See [Compatibility with GitHub Actions](https://diffinery.com/docs/actions/compatibility).
138
139**What does it cost to run?**
140Diffinery is free and open source under the Apache License 2.0. Running it costs whatever your own Cloudflare account bills: the Workers Paid plan plus usage. Hosted runners are Cloudflare Containers, which bill only while a job runs.
141
142**Does it work with AI coding agents?**
143Yes. Agents connect over MCP (`https://<your host>/mcp`), the REST API, git or the GitHub CLI. There are guides for Claude, Claude Code, Codex, Cursor and VS Code, and a plugin for Claude Code and Codex, installable with `claude plugin marketplace add https://diffinery.com/codician/diffinery.git` (sources in [`plugins/`](plugins)). See [Connect AI apps](https://diffinery.com/docs/connect).
144
145**Can I move my repositories from GitHub?**
146Yes. The importer brings a repository or a whole organization with history, issues, pull requests, reviews and releases. Secret names come over with a field to enter each value. See [Migrate from GitHub](https://diffinery.com/docs/migrate-from-github).
147
148**Where is development happening?**
149On Diffinery itself, at [diffinery.com/codician/diffinery](https://diffinery.com/codician/diffinery). Diffinery's own CI, deploys and pull requests run there. The GitHub repository is a mirror.
150
151## Contributing, security and license
152
153- **Contributing:** see [CONTRIBUTING.md](CONTRIBUTING.md). Please follow the [Code of Conduct](CODE_OF_CONDUCT.md).
154- **Security:** please don't open public issues for vulnerabilities. Report them privately as described in [SECURITY.md](SECURITY.md).
155- **License:** [Apache License 2.0](LICENSE). See [NOTICE](NOTICE).