Import a GitHub repository

POST/api/github/imports

createGithubImport

Creates a new neosource repository in the workspace named by `owner` and enqueues a background import that clones the GitHub repo into it. Watch progress via the repo's `import-progress` SSE / `import-status` endpoints. `owner` omitted (or the caller's own handle) is the caller's personal workspace. Every target, the personal workspace included, must be a workspace where the caller holds `workspace:repo:create`; an unknown owner answers `404` and one without the permission `403`, both **before the repository is created**. The import runs on the caller's own GitHub credential whichever workspace receives it. `visibility` omitted mirrors the GitHub repository: public on GitHub is `public` here; private (and GitHub `internal`) is `private`, as is any import whose GitHub visibility could not be read. An explicit `visibility` always wins. `relationship` says what tie to keep with the GitHub repository (ADR 0115). `neosource_readonly_mirror` imports issues, comments and labels and keeps them in sync, GitHub staying authoritative. `github_managed` is sync at import: the repository is bound to the GitHub App installation covering `source_full_name` and, once the clone completes, attached to it (a clean attach confirms itself; anything that would move or preserve a ref waits as a preview on the repository's GitHub panel). It needs `workspace:integration:manage` on the target workspace (`403`; a token must carry that scope), a session or a token not locked to workspaces or repositories (`403`), a token whose scopes reach `repo:admin` (`403`), and an installation the caller may use that covers the repository and is not already linked to another neosource repository (`409 relationship_conflict`, the detail naming the install page or the conflict); `409 relationship_unavailable` when this deployment does not offer GitHub sync. `move_now` answers `409 relationship_unavailable`. Every one of these refusals lands **before the repository is created** so a refusal never leaves an orphan behind. The deprecated `sync_metadata: true` means exactly `relationship: "neosource_readonly_mirror"`; sending both is `400`. Two further refusals land at that same early point, so neither can orphan a repository either: asking for `neosource_readonly_mirror` without a linked GitHub identity carrying a stored access token answers `400` (connect GitHub in account settings first — it is the credential the metadata backfill and the recurring polls run on), and a token locked to specific repositories or workspaces answers `403`, because every import spends the owner's stored GitHub credential on a repository the token was never scoped to. Sessions and unrestricted tokens are unaffected. The import queue is bounded: `429` when the caller already has the per-user maximum of imports queued or running, `503` when the platform-wide queue is full. Both are retryable and carry `Retry-After`, and both land before any GitHub call and **before the repository is created**.

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

curl

curl -X POST 'https://neosource.dev/api/github/imports' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"source_full_name":"string"}'

fetch

fetch("https://neosource.dev/api/github/imports", {
  method: "POST",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"source_full_name":"string"}),
});

Request bodyrequired

application/json

CreateGithubImportRequest

object

Request to import a GitHub repo into a new neosource repo.

owner: string | null
The organization workspace slug to import into. Omitted (or the caller's own handle) = the caller's personal workspace. Every target, the personal workspace included, needs `workspace:repo:create` there, asked of the policy layer before the repository is created. The import still runs on the caller's own linked GitHub credential either way.
relationship: one of
GithubImportChoice
string
Relationship choices shown at import time. `GithubBackup` is intentionally absent, and `MoveNow` is an import transition rather than a stable relationship mode.
"github_managed""neosource_readonly_mirror""move_now"
null
source_full_namerequired: string
`owner/name` on GitHub to import.
sync_metadata: booleandeprecated
**Deprecated** — send `relationship` instead. Also import and keep syncing the repo's issues, comments and labels (plans/github-metadata-import.md): the `github_repo_sync` row is created before the repo becomes writable and the metadata backfill job is enqueued once the git import completes. `true` is exactly `relationship: "neosource_readonly_mirror"`. Omitted = `false`, git contents only. Kept, NOT removed, for the whole 4a/4b rollout window: this struct is `deny_unknown_fields`, and the SPA is versioned independently of the api image, so a pod that no longer accepted this field would 400 every import a not-yet-updated bundle sends. It goes away in Phase 4c. Sending BOTH this and `relationship` is `400 invalid_input` rather than a precedence rule — two statements of one intent must not be silently resolved in favour of either.
target_name: string | null
Optional name for the created neosource repo; defaults to the GitHub repo name.
visibility: one of
RepoVisibilityInput
string
"public""internal""private"
null

additional propertiesnot allowed

Responses

202Repo created and import enqueued

application/json

ImportEnqueuedResponse

object

Returned by `POST /api/github/imports` once the target repo is created and the import job is enqueued. The SPA navigates to `/{owner}/{repo}` and watches the existing import-progress SSE.

job_idrequired: string
Import job id (for debugging / correlation).
ownerrequired: string
reporequired: string

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
404Not Found — one of: not_found
409Conflict — one of: already_exists, conflict, relationship_conflict, relationship_unavailable
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget