Update repository settings

PATCH/api/repos/{owner}/{repo}/settings

updateRepositorySettings

Updates mutable repository metadata: visibility (public/internal/private), description, and the merge-method pair (`allowed_merge_methods` — the methods this repo permits — and `default_merge_method` — the one used when a merge request names none), and `delete_branch_on_merge` — whether a merge also removes the pull request's source branch, on unless a repo turns it off. Omitted fields are left unchanged. The allow-list must be non-empty, duplicate-free, and must contain the resulting default; a request whose RESULTING state breaks that is rejected with 400 rather than silently repaired. It is a set, so it is stored and echoed in a canonical order (`merge` before `squash`) regardless of the order sent. Pass `expected_version` (the `version` from the last read) for optimistic concurrency — a concurrent edit returns 409, as does the rarer case of a request validated against a repo record that changed underneath it (retry after re-reading). Requires repo admin access. `workspace_secrets` (`auto` / `enabled` / `disabled`) — whether trusted CI runs on this repo receive the workspace's CI secrets and may write its shared compile cache; `auto` grants them exactly while the repo's creator is currently an owner or admin of its workspace (repo grants do not count) — additionally requires `workspace:secret:write` on the repo's workspace (the right to manage those secrets), so a repo admin who is not a workspace admin gets 403 for it. `ci_workflow_source` (`neosource` / `neosource_and_github`) — whether `.github/workflows/` files run in place beside `.neosource/workflows/` (a `.github` file named like a native one is shadowed by it). Turning it on registers the default branch's current files before responding and starts no run itself (a promoted `on: schedule` workflow fires at its next tick, the others on the next push); turning it off stops new runs, re-runs and approvals of them in the same write, without cancelling runs already queued or in progress.

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

curl

curl -X PATCH 'https://neosource.dev/api/repos/OWNER/REPO/settings' \
  -H 'Authorization: Bearer $NEOSOURCE_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{}'

fetch

fetch("https://neosource.dev/api/repos/OWNER/REPO/settings", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer $NEOSOURCE_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

Path parameters

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

Request bodyrequired

application/json

UpdateRepoRequest

object

Request body for `PATCH /api/repos/{owner}/{repo}/settings` — update mutable repo metadata. All fields optional; omitted fields are left unchanged. `expected_version` enables optimistic concurrency: supply the `version` last read so a concurrent edit is rejected with 409.

allowed_merge_methods: array | null
The methods this repo permits at all. Must be non-empty and free of duplicates, and must contain the resulting `default_merge_method` — so patching this field alone cannot orphan the stored default. Order is not significant: the value is a set, and the server stores it in a canonical order rather than the order sent.
items
MergeMethod
string
How a pull request's commits land on its target branch. A repo carries two settings over this enum (`migrations/20260820120000_repo_merge_methods.sql`): the set it *permits* (`RepoRecord::allowed_merge_methods`, never empty) and the one the merge path reaches for when the request names none (`RepoRecord::default_merge_method`, always a member of that set — enforced by the settings route, which is the only place both columns are visible at once). `Default` is [`MergeMethod::Merge`] to match the column default, which is itself the pre-existing behaviour of every repo: before this setting existed, a merge always minted a two-parent commit. `Rebase` is deliberately absent rather than merely unimplemented — it replays N commits, can conflict per commit, and rewrites the SHAs the stacked-PR re-parent invariant leans on (`plans/archive/pr-merge-methods-2026-08.md` §"Not doing"). Adding it later is one `ALTER TYPE merge_method ADD VALUE` plus an arm here, which is why the stored shape is an enum array and not a pair of booleans.
"merge""squash"
ci_workflow_source: one of
CiWorkflowSource
string
Which workflow directories a repository runs (`repos.ci_workflow_source`, ADR 0159). A per-repo setting changed by a repo admin through `PATCH /api/repos/{owner}/{repo}/settings`. Two values on purpose — there is no "GitHub only": `.neosource/workflows/` always runs, so a repo that opts in runs both directories, exactly as GitHub would run both sets if it read them.
"neosource""neosource_and_github"
null
default_merge_method: one of
MergeMethod
string
How a pull request's commits land on its target branch. A repo carries two settings over this enum (`migrations/20260820120000_repo_merge_methods.sql`): the set it *permits* (`RepoRecord::allowed_merge_methods`, never empty) and the one the merge path reaches for when the request names none (`RepoRecord::default_merge_method`, always a member of that set — enforced by the settings route, which is the only place both columns are visible at once). `Default` is [`MergeMethod::Merge`] to match the column default, which is itself the pre-existing behaviour of every repo: before this setting existed, a merge always minted a two-parent commit. `Rebase` is deliberately absent rather than merely unimplemented — it replays N commits, can conflict per commit, and rewrites the SHAs the stacked-PR re-parent invariant leans on (`plans/archive/pr-merge-methods-2026-08.md` §"Not doing"). Adding it later is one `ALTER TYPE merge_method ADD VALUE` plus an arm here, which is why the stored shape is an enum array and not a pair of booleans.
"merge""squash"
null
delete_branch_on_merge: boolean | null
Whether merging a PR also deletes its source branch. No cross-field invariant binds this one, so it is written through as sent; every condition that can stop a particular deletion is evaluated at merge time, not here.
description: string | null
expected_version: integer | nullint32
mirror_source_url: string | null
visibility: one of
RepoVisibilityInput
string
"public""internal""private"
null
workspace_secrets: one of
WorkspaceSecretsPolicy
string
Whether trusted CI runs on a repository receive its workspace's CI secrets and may write the workspace-shared compile cache. `auto` decides from the repository's creator at each use: eligible exactly while the creator is an owner or admin of the repository's workspace. `enabled` / `disabled` are a workspace admin's explicit decision.
"auto""enabled""disabled"
null

additional propertiesnot allowed

Responses

200Repository updated

application/json

RepoResponse

object

activity_at

integer | nullint64

When the repo last changed, as the owner list sorts and shows it (ms since the epoch): the later of `updated_at` (a settings write) and its last push. Present only on `GET /api/owners/{handle}/repos` rows, whose statement reads it; absent (not `null`) everywhere else. Set only through [`RepoResponse::with_activity_at`].

allowed_merge_methodsrequired

array

Which merge methods this repo permits at all. Never empty, and always in a canonical order (`merge` before `squash`) — it is a set, so the server normalises the order on write rather than echoing the order it was sent.

items

MergeMethod

string

How a pull request's commits land on its target branch. A repo carries two settings over this enum (`migrations/20260820120000_repo_merge_methods.sql`): the set it *permits* (`RepoRecord::allowed_merge_methods`, never empty) and the one the merge path reaches for when the request names none (`RepoRecord::default_merge_method`, always a member of that set — enforced by the settings route, which is the only place both columns are visible at once). `Default` is [`MergeMethod::Merge`] to match the column default, which is itself the pre-existing behaviour of every repo: before this setting existed, a merge always minted a two-parent commit. `Rebase` is deliberately absent rather than merely unimplemented — it replays N commits, can conflict per commit, and rewrites the SHAs the stacked-PR re-parent invariant leans on (`plans/archive/pr-merge-methods-2026-08.md` §"Not doing"). Adding it later is one `ALTER TYPE merge_method ADD VALUE` plus an arm here, which is why the stored shape is an enum array and not a pair of booleans.

"merge""squash"

created_atrequired

integerint64

created_byrequired

string

default_branchrequired

string

default_merge_methodrequired

MergeMethod

string

"merge""squash"

delete_branch_on_mergerequired

boolean

Whether merging a PR against this repo also deletes its source branch. `true` on a repo nobody has configured — see the settings route for why this one defaults on where the merge-method fields default to today's behaviour.

descriptionrequired

string

mirror_source_url

string | null

mirror_status

one of

RepoMirrorStatus
object
[`RepoResponse::mirror_status`]: how current a `_mirror` repository is.
last_synced_at
integer | nullint64
When the daily refresh last synced from the upstream (ms since the epoch); absent before the first sync.
latest_ci
one of
CommitStatusState
null
null

ownerrequired

string

parent

one of

RepoParentInfo
object
Summary of a fork's parent repository.
repo_idrequired
string
null

primary_language

string | null

The default branch's primary language: the language with the most code lines in the stored breakdown (ADR 0105, ADR 0187). Absent until a fill under the current classification policy has run, and for a repo with no code. An open vocabulary (tokei's names), like `LanguageStat::name`.

repo_idrequired

string

slugrequired

string

star_count

integer | nullint64

All-time star count. Present on exactly four routes — `GET /api/user/stars`, `GET /api/users/{handle}/stars`, `GET /api/repos?sort=trending` and `GET /api/owners/{handle}/repos` — whose store reads carry the count in the same statement. Absent (not `null`) everywhere else, including the default `GET /api/repos`: the repo detail's `stats.star_count` is the per-repo source. Set only through [`RepoResponse::with_star_count`].

statusrequired

RepoStatusOutput

string

Repo lifecycle state surfaced by the API. Mirrors `RepoStatus`. See ADR 0012 §2.

"creating""ready""importing""import_failed"

updated_atrequired

integerint64

versionrequired

integerint32

visibilityrequired

RepoVisibilityInput

string

"public""internal""private"

workspace_idrequired

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, non_fast_forward
423Locked — one of: busy
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

Schemas

Referenced above. Listed here rather than expanded inline, so the same definition is not repeated at every level.

`CommitStatusState`

string

State of a single commit status, GitHub-shaped. `Error` is distinct from `Failure` on individual statuses (infrastructure/tooling breakage vs. a real red result) but the combined rollup folds both into `Failure`.

"pending""success""failure""error"