Import a GitHub repository

POST/api/github/imports

createGithubImport

Creates a new neosource repository in the caller's personal workspace and enqueues a background import that clones the GitHub repo into it. Watch progress via the repo's `import-progress` SSE / `import-status` endpoints. `relationship` says what tie to keep with the GitHub repository (ADR 0115). In this build only `neosource_readonly_mirror` can be established — issues, comments and labels are imported and kept in sync, and GitHub stays authoritative. `github_managed` and `move_now` answer `409 relationship_unavailable`, refused **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.

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.

relationship: one of
null
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"
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
null
RepoVisibilityInput
string
"public""internal""private"

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
404Not Found — one of: not_found
409Conflict — one of: already_exists, 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