neosource is pre-alpha: expect breaking changes, and it is
free for now. 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.
Every row below was checked against the code. Each one has one of three
statuses:
- Works: built, in use, and documented where a page is linked.
- Sharp edge: works, but it will surprise you if you do not know the caveat.
- Not built: designed or missing. Nothing in the product does it yet.
| Feature |
Status |
Caveat |
Docs |
| Clone, fetch and push over HTTPS and SSH |
Works |
Ordinary git and ordinary remotes. jj works too, because it fetches and pushes over Git. |
Getting started |
| Shallow and partial clones |
Sharp edge |
--depth works over v2, and over v0 on HTTPS. --filter needs v2. --shallow-since and --shallow-exclude are rejected, and SSH v0 has neither. |
— |
| Git LFS |
Sharp edge |
The batch API with basic transfers works. File locking (/locks) answers 501 Not Implemented. |
Large files |
| Push and object size limits |
Sharp edge |
A push over 5 GiB, or an object over 2 GiB, is rejected. |
Large files |
| Browsing code, commits, file history and tags |
Works |
Also a zip download of any ref. |
— |
| Forks and stars |
Works |
A fork is a full copy and counts against its owner’s storage quota. |
Storage and quota |
| Branch protection |
Works |
Settings → Branches, or neo repo protection. |
neo repo |
| Webhooks |
Works |
With a delivery log, ping and redelivery. No guide yet. |
— |
| Push mirrors |
Works |
Push-only. Mirrors to GitHub live under Settings → GitHub, all others under Settings → Mirrors. |
Keep GitHub as a mirror |
| Getting back a deleted branch |
Sharp edge |
Fetch its old tip by SHA within 30 days and push it again. There is no undo button and no ref history in the product. |
Recovering branches |
| Getting back a force-pushed branch |
Sharp edge |
Not retained, except an open same-repo PR’s old head, kept 30 days. Push the old tip back from a clone that still has it. |
Recovering branches |
| Feature |
Status |
Caveat |
Docs |
Open, review and merge, on the web and with neo pr |
Works |
— |
Pull requests |
| Stacked pull requests |
Sharp edge |
Inside one repository. The Stack panel shows one line of up to 32 PRs. Merging the bottom re-targets the next one but does not rebase it. |
Code review |
| Review threads that follow a force-push |
Works |
— |
Code review |
| Required checks and required reviews |
Sharp edge |
The author’s own approval never counts toward the required number. |
Code review |
| Auto-merge and the merge queue |
Sharp edge |
Pushing a new head takes the PR out of the queue; someone has to arm it again. |
Code review |
| Flaky-test detection and quarantine |
Works |
A quarantined test no longer gates merges. Repo settings → Quarantine. No guide yet. |
— |
| Image attachments on PRs and issues |
Works |
neo attachment downloads them. |
neo attachment |
| Feature |
Status |
Caveat |
Docs |
Team tickets (KEY-N), boards and labels |
Works |
— |
Planning |
Repository issues (owner/repo#N) |
Works |
— |
Planning |
| Cycles and triage |
Works |
— |
Planning |
Fixes / Closes links from PRs |
Sharp edge |
acme/api#42 parses but links only when it names the PR’s own repository. Cross-workspace links do not exist. |
Planning |
| Tickets and issues from the CLI |
Works |
neo ticket and neo issue. |
Tickets and issues |
| Search |
Sharp edge |
Covers issues, pull requests and comments. There is no code search. |
— |
| Notifications |
Sharp edge |
An inbox in the web app, updated live. Notifications are not sent by email. |
— |
| Feature |
Status |
Caveat |
Docs |
Workflows in .neosource/workflows/ |
Works |
GitHub Actions YAML. Top level of the directory only, read from the default branch. |
How CI works here |
Workflows in .github/workflows/ |
Sharp edge |
Parsed and shown on the Actions tab, but nothing runs until a repo admin turns it on (Actions tab banner, Settings → General, or neo repo set --ci-workflow-source neosource-and-github). |
How CI works here |
push, pull_request, merge_group, schedule, workflow_dispatch |
Works |
pull_request fires on opened and synchronize by default; closed, draft flips, edited and review_requested when listed in types:. |
Writing a workflow |
| Real upstream actions |
Works |
Composite, Docker and Node actions, mirrored and SHA-pinned by the platform. |
Actions, secrets and variables |
| Artifact actions |
Sharp edge |
actions/upload-artifact and download-artifact need @v4. @v1 to @v3 fail with GitHub’s deprecation error. |
Coming from GitHub Actions |
packages: and flake: job environments |
Works |
image: is a parse error; container: is ignored with a warning. |
The job environment |
services: |
Sharp edge |
Hosted runners only, not neo runner or neo run. A host:container port remap is not applied. |
Coming from GitHub Actions |
| Caching |
Works |
Per-repository copy-on-write cache disks, plus actions/cache. |
Setup time, caching and billing |
paths: on pull_request |
Sharp edge |
Measures the whole base..head diff, not the latest commit, so a docs-only follow-up still runs a src/** check. |
Coming from GitHub Actions |
| Branch and path globs |
Sharp edge |
* does not cross /: release/* does not match release/v1/rc1, as on GitHub. |
Coming from GitHub Actions |
Job-level continue-on-error |
Sharp edge |
Ignored on hosted runners; only neo run honours it. |
Coming from GitHub Actions |
always() after a cancel |
Sharp edge |
A cancel is final: always() jobs that have not started do not run, and cancelled() is never true. |
Coming from GitHub Actions |
| Live logs, re-runs and approvals |
Works |
On the Actions tab and with neo actions. |
neo actions |
| Secrets and variables |
Works |
— |
Actions, secrets and variables |
| Running a workflow locally |
Works |
neo run <file>. |
neo run |
| CI minutes and storage usage |
Works |
Per workspace, on its Usage page. |
Setup time, caching and billing |
Reusable workflows, permissions:, environment: |
Not built |
A job that uses: a workflow is skipped; the two keys are accepted and ignored. |
Coming from GitHub Actions |
repository_dispatch, on: change, other events |
Not built |
They parse but never start a run. |
How CI works here |
| Feature |
Status |
Caveat |
Docs |
| Hosted runners |
Works |
One VM per job, Linux x86_64 only. |
Runners |
| Your own machine as a runner |
Works |
neo runner start. It claims only jobs from runs you triggered unless registered --workspace-wide. |
Runners |
| Headless enrollment |
Works |
neo runner enroll, for machines nobody signs in on. |
neo runner |
| Local-first CI |
Works |
neo push --runner runs your push’s jobs here and streams their logs; the hosted pool takes over if this machine dies. |
neo push |
| Runner registrations |
Sharp edge |
A registration not seen for 24 hours is removed. A running neo runner start re-registers by itself; one resumed after a restart exits and needs neo runner register. |
Runners |
| Self-hosted VM runners |
Sharp edge |
The separate ns-runner agent, on Linux with KVM, runs jobs in VMs like the hosted pool, services: included. |
Runners |
| Windows and macOS runners |
Not built |
— |
Runners |
| Feature |
Status |
Caveat |
Docs |
| Install on macOS, Linux and Windows |
Works |
curl -LsSf https://get.neosource.dev | sh, then neo upgrade keeps it current. |
Install the CLI |
| Sign-in, git credentials and SSH keys |
Works |
neo auth login also sets neo up as git’s credential helper. |
neo auth, neo ssh |
| Repositories, PRs, tickets, issues, runs |
Works |
You do not need the CLI: Git plus the web app covers the whole basic loop. |
CLI reference |
| Creating an organization |
Sharp edge |
Web only, at /new/organization. neo org only claims a handle held by a GitHub organization. |
neo org |
| Agent session uploads |
Works |
neo sessions setup installs the agent hooks; off until you run it. See Agent sessions. |
neo sessions |
| Offline reference |
Works |
neo docs prints this reference from the binary itself. |
neo docs |
| Feature |
Status |
Caveat |
Docs |
docker push and docker pull |
Works |
At neocr.io/{owner}/{name}, with an access token or the CI job token. |
Container registry |
| Anonymous pull of public images |
Works |
An image’s visibility is its own, not its repository’s. |
Container registry |
| Packages in the web app |
Works |
A repository’s Packages tab, and a page per package listing its tags and the run that pushed each. |
— |
| Changing an image’s visibility |
Sharp edge |
API only; the web app shows it but cannot change it. |
Container registry |
Catalog listing (/v2/_catalog) |
Not built |
Use tags/list on a namespace you can read. |
Container registry |
| Feature |
Status |
Caveat |
Docs |
| Releases with downloadable assets |
Works |
neo release create <tag> <files>, from a laptop or a CI job. Drafts, prereleases and one rolling release per repository. |
neo release |
| A releases page in the web app |
Not built |
Read releases with neo release list and neo release view, or the API. |
neo release |
| Publishing to package managers |
Not built |
Homebrew, AUR and the like are designed (ADR 0184), not built. |
— |
on: release workflow trigger |
Not built |
Warned about and dropped. |
Coming from GitHub Actions |
| Feature |
Status |
Caveat |
Docs |
| Import from a public Git URL |
Works |
Code and history only, from any host. |
Migrating from GitHub |
neo adopt and neo migrate |
Works |
Push local checkouts here; --mirror-back keeps the old GitHub home updated. |
neo adopt, neo migrate |
| GitHub import, private repositories included |
Works |
Needs a linked GitHub account. Open pull requests do not become pull requests here. |
Migrating from GitHub |
| Sync with GitHub |
Sharp edge |
GitHub stays the ref authority. A pull request opened here cannot be merged here while sync is on. |
Migrating from GitHub |
| Read-only mirror of a GitHub repository |
Sharp edge |
Keeps code, issues, pull requests, comments and labels for reading. Set it up before filing anything here; numbers cannot be shifted later. |
Migrating from GitHub |
| Moving a read-only mirror to neosource |
Works |
Settings → GitHub → Move to neosource. Every ref and synced issue stays. |
Migrating from GitHub |
| Importing from GitLab, Bitbucket or Gitea |
Not built |
Their public repositories come in through the public Git URL route, without metadata. |
Migrating to neosource |
| Importing issues from Linear, Jira or GitLab |
Not built |
— |
Migrating to neosource |
| Feature |
Status |
Caveat |
Docs |
| Sign-in |
Works |
Handle and password, a passkey, GitHub, or a one-time link sent to your email. |
— |
| Two-factor authentication |
Works |
TOTP with recovery codes, or a passkey. |
— |
| Personal and workspace access tokens |
Works |
Fine-grained and expiring; 90 days unless you choose otherwise. |
Authentication and tokens |
| Claiming a GitHub handle or organization |
Works |
By proving you control it on GitHub. |
neo org |
| Organizations, members and teams |
Works |
An invite goes to an email address and can be accepted only by an account that has it verified. |
Workspaces and the web app |
| Per-repository access |
Works |
Grant a team or an account a role on one repository, or invite by email. |
— |
| Deleting your account |
Not built |
Designed (ADR 0196), not built. |
— |
| Feature |
Status |
Caveat |
Docs |
| Uploading coding-agent sessions |
Works |
Claude Code, Codex and Antigravity, through a hook neo sessions setup installs. Off until you turn it on. |
Agent sessions |
| Redaction |
Works |
On your machine before upload, then checked again by the forge, which rejects a bundle that still matches a rule. |
Agent sessions |
| Reading sessions |
Works |
/sessions, a viewer per session, and a Sessions tab on each pull request. |
Agent sessions |
| Who can see a session |
Works |
Only readers or writers of every repository it touched, depending on its visibility. |
Agent sessions |
| Links to commits |
Sharp edge |
A session links to a commit only when the commit’s author email is a verified address of your account. neo sessions status warns when it does not. |
neo sessions |
| Feature |
Status |
Caveat |
Docs |
| A home per workspace |
Works |
/ for your personal workspace, /<org> for an organization, with its members’ work band. |
Workspaces and the web app |
| Explore and Starred |
Works |
Trending repositories live in Explore. |
Workspaces and the web app |
| Inbox, review requests and your issues |
Works |
— |
Workspaces and the web app |
| Blame view |
Not built |
— |
— |
| Code search |
Not built |
Search covers issues, pull requests and comments. |
— |
| Feature |
Status |
Caveat |
Docs |
| Static sites from a repository |
Sharp edge |
At <owner>.neosource.page/<repo>/ or a custom domain. A private repository publishes only with the public-site consent. Deployed by actions/deploy-pages from the source branch; Settings → Pages enables and rolls back. |
Publishing a site with Pages |
The gaps from every table above, in one place:
- CI: reusable workflows,
permissions:, deployment environment:,
repository_dispatch, on: change, the release and issues triggers, a
CI status badge, and Windows or macOS runners.
- Releases: a releases page in the web app, and publishing to package
managers.
- Registry: the
/v2/_catalog listing.
- Git: LFS file locking,
--shallow-since and --shallow-exclude, and any
undo for a push or a branch delete.
- Web app: a blame view and code search.
- Planning: links across repositories and workspaces, and notifications
by email.
- Importing: private-repository imports from GitLab, Bitbucket or Gitea, and
issue imports from anything but GitHub.
- Accounts: deleting your account.
Using neosource for real work is reasonable if your workflow is Git, pull
requests and GitHub-Actions-style CI on Linux, and you can live with the CI
gaps above. It is not yet a drop-in replacement for every GitHub surface: the
areas most likely to be missing something you rely on are CI trigger coverage,
Windows and macOS builds, and the pages the web app has not grown yet, such as
releases and blame.
Documentation follows implementation. If something is not on this page or
documented elsewhere, assume it is not built rather than undocumented.