Project status

neosource is pre-launch. Rather than hedging on every page, this is the one page that tracks what is real — so the rest of the documentation can describe things plainly and you can check here when you want the caveats.

If a page describes a behaviour, it has been verified against the running code. Where something is designed but not built, it is called out where you would look for it, not omitted.

Works today

Git. Clone, fetch and push over HTTPS and SSH. Ordinary git, ordinary remotes. This is the most exercised surface in the product.

jj. Works against the same URLs via jj git clone / jj git push, because jj speaks Git. The protocol edge handles jj’s libgit2-driven negotiation explicitly.

The web app. Code browsing, commits, stacked pull requests with a merge queue, two-track planning (team tickets and repo issues, cycles, triage), an Actions view for CI, and an operation log view. The signed-in home is one account-scoped page: your work (review requests, your open PRs, issues assigned to you), recent activity, trending and starred repositories.

CI. Workflows in .neosource/workflows/ (and .github/workflows/ once enabled) run in isolated per-job VMs on hosted runners, triggered by push, pull request, merge group, cron, and manual workflow_dispatch. Jobs run real upstream GitHub Actions with pre-cached toolchains, persistent copy-on-write cache disks, and declarative Nix packages: or flake:. Logs stream live. See How CI works here.

The neo CLI. Installable on macOS, Linux and Windows — curl -LsSf https://get.neosource.dev | sh. You do not need it: Git plus the web UI covers the whole basic loop. It exists for what a browser is bad at — reading and claiming issues and tickets, opening and merging pull requests, managing tokens, running a workflow locally, and turning your own machine into a runner. See Install the CLI.

Self-hosted runners. neo runner start registers this machine and claims jobs by long-poll, with lease heartbeat and completion, or you can enroll headless machines with neo runner enroll. The agent is embedded in the CLI, so there is no second binary to install. Registration is actor-bound by default — it claims only jobs from runs you triggered. See Runners.

Local-first CI. neo push --runner runs the CI your push triggers on your own machine: an ephemeral session runner claims that push’s jobs and streams their logs into your terminal, while the server keeps real run records visible in the UI. The hosted pool is the fallback if your machine dies mid-run.

Container registry. docker push and docker pull against neocr.io/{owner}/{name}, on the same accounts and permissions as your code, authenticated with an ordinary access token or the automatic CI job token. See Container registry.

Importing and GitHub sync. From a public Git URL, neo adopt / neo migrate from local checkouts, or an authenticated GitHub import for private repositories, with optional github_managed attach/detach ref sync and issue/comment/label sync.

Auth. Accounts, passkeys and TOTP, SSH keys, GitHub handle and organization claim by proof, and fine-grained personal and workspace access tokens.

Sharp edges

Things that work but will surprise you:

• Workflows live in .neosource/workflows/. A .github/workflows/ directory is parsed and reported on the Actions tab, but nothing in it runs until a repo admin enables it (neo repo set --ci-workflow-source neosource-and-github) — the most common cause of “why is nothing running”.
• Artifact actions require @v4. actions/upload-artifact and actions/download-artifact at @v1–@v3 fail immediately with GitHub’s deprecation error.
• paths: on pull_request measures the whole base..head diff, not the latest commit — so a docs-only follow-up still runs a paths: ['src/**'] check if an earlier commit on the PR touched src/.
• Glob matching is strict. release/* does not match release/v1/rc1 — the same rule GitHub Actions applies, which still catches people out.
• The registry has no web UI. Images push and pull fine, but they are only readable through the API: there is no image browser, and the repository catalog (/v2/_catalog) is not implemented.
• A runner registration is swept after 24 hours without claiming a job. A machine left off for a day comes back to a dead credential. neo runner start re-registers itself and resumes, on a restart as much as while running, so in practice this is invisible — the only limit is a bounded retry budget, which makes an agent the scheduler keeps rejecting exit non-zero instead of churning.

The full CI inventory is in Coming from GitHub Actions.

Not built yet

• on: change, the jj-native change trigger. Designed, not dispatched.
• Reusable workflows, permissions:, and deployment environment:.
• Windows and macOS CI runners. Linux only.
• A jj-native wire protocol. jj works because jj speaks Git; there is no second protocol on the wire.

What this means for you

Using neosource for real work is reasonable if your workflow is Git plus CI, and you can live with the CI gaps above. It is not yet a drop-in replacement for every GitHub surface, and the areas most likely to be missing something you rely on are CI trigger coverage and the surfaces the web UI has not grown yet.

Documentation breadth follows implementation, not ambition. If something is not documented here, assume it is not built rather than undocumented.