Preview what a GitHub mirror would change on GitHub

GET/api/repos/{owner}/{repo}/mirrors/github/preview

previewGithubMirror

What a push mirror through the neosource GitHub App to `target` would do to GitHub right now: the refs it would delete, the refs it would force-update (with whether each update is a fast-forward), how many branches it would create or leave alone, and GitHub's default branch when the push keeps it rather than deleting it. Computed exactly as the mirror's push computes its command set, from this repository's current branches and GitHub's current refs. Writes nothing, here or on GitHub. Requires repo admin and a GitHub App installation you may use that reaches `target` with `contents` and `workflows` write — the same check `POST …/mirrors/github` makes, refused the same way: `403 github_app_install_required` (its `message` carries the fix) when no such installation covers it, or GitHub answers that it is uninstalled, suspended or no longer reaches `target`; `403 github_app_permission_missing` (body `GithubAppPermissionMissingError`) when one does without a mirror's permissions. `404` when this deployment has no GitHub App configured. Whether the mirror itself would be admitted (the same-target guard) is not answered here.

Requires authentication using a bearer token or a session cookie — see tokens and scopes.

curl

curl -X GET 'https://neosource.dev/api/repos/OWNER/REPO/mirrors/github/preview?target=TARGET' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN'

fetch

fetch("https://neosource.dev/api/repos/OWNER/REPO/mirrors/github/preview?target=TARGET", {
  method: "GET",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
  },
});

Path parameters

ownerrequired: Repository owner or organization slug.
string
reporequired: Repository name.
string

Query parameters

targetrequired: The GitHub `owner/name` a mirror would push to.
string

Responses

200What the mirror's push would do

application/json

GithubMirrorPreviewResponse

object

What a GitHub App push mirror to `target` would do to GitHub **right now** (ADR 0122): the exact-replica command set the mirror's first push computes, over this repository's current refs and GitHub's current advertisement. Nothing is written on either side to produce it. A mirror replicates `refs/heads/*` and `refs/tags/*` exactly: every branch here is created or force-updated there, and every branch or tag there that is not here is deleted — except GitHub's default branch, which GitHub refuses to delete and the push keeps (`default_branch_kept`). This repository carries no tags of its own, so every GitHub tag is deleted. A snapshot: GitHub can move between this read and the first push, which replicates whatever GitHub holds then (`compared_at` says when this was).

compared_atrequired

integerint64

Epoch milliseconds of the comparison.

default_branch_kept

string | null

GitHub's default branch (`refs/heads/…`) when the replica would delete it and keeps it instead; `null` otherwise.

github_matchesrequired

boolean

`true` when the push would change nothing: every list below is empty and `will_create_count` is 0. GitHub's default branch may still be one this repository lacks (`default_branch_kept`).

targetrequired

string

GitHub's canonical `owner/name` for the target — what it answered, which differs from the requested name after a rename or transfer.

unchanged_countrequired

integerint32

Branches already at the same commit on both sides.

will_create_countrequired

integerint32

Branches this repository has and GitHub does not: the push creates them.

will_deleterequired

array

Refs GitHub has and this repository does not: the push deletes them.

items

MirrorPreviewRef

object

A ref the mirror would delete on GitHub.

github_oidrequired: string
The 40-hex commit (or tag object) GitHub's ref points at.
namerequired: string
Full ref name, `refs/heads/…` or `refs/tags/…`.

will_overwriterequired

array

Refs both sides have at different commits: the push moves GitHub's to this repository's commit, discarding whatever only GitHub's held.

items

MirrorPreviewOverwrite

object

A ref the mirror would force-update on GitHub.

fast_forwardrequired: boolean
`true` when `github_oid` is proven an ancestor of `local_oid` from this repository's own objects: the update loses nothing on GitHub. `false` when it is not — GitHub's commits there are discarded — and also when that could not be proven within the walk's bounds; never fetched from GitHub. A commit this repository does not hold cannot be an ancestor of one it does, so `false` is exact for it.
github_oidrequired: string
The 40-hex commit GitHub's ref points at now.
local_oidrequired: string
The 40-hex commit this repository's ref points at — where the push moves GitHub's.
namerequired: string
Full ref name, `refs/heads/…`.

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bad Request — one of: invalid_input
401Authentication required
403Forbidden — one of: forbidden, github_app_install_required, github_app_permission_missing
404Not Found — one of: not_found
423Locked — one of: busy
429Rate limited — retry after the `Retry-After` header
500Internal server error
502Bad Gateway — one of: upstream
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget