Git remote

Included from Basic tier

JSON:API type: git_remote.

The v2 OpenAPI document declares this resource's schema; the resource-field coverage gate holds this page to it.

A git remote is a project-scoped repository registration: the URL plus the credentials templates and template versions use to fetch it.

Endpoints

All under /api/projects/{project_code}/git_remotes:

Verb	Path	Behaviour
GET	…/git_remotes	Index — each remote gated by read on the project's …/git_remotes rule path. meta.authorisations reports update/delete on that path, plus default_periodic_fetch_interval (added only when the project itself is readable). Accepts the shared Ransack filter grammar; the sensitive columns are excluded from the allowlist, so filter[user_*], filter[password_*] and filter[ssh_key_data_*] are rejected 400. Default order: created_at ascending, id ascending.
POST	…/git_remotes	Create — project readable plus update on …/git_remotes, 404-on-deny. 201, or 422 with the model errors. A credentialed create on a server with no encryption keys configured answers 503 (see below).
GET	…/git_remotes/{id}	Show — a missing project, a remote outside the project, or a read denial all answer 404.
PATCH/PUT	…/git_remotes/{id}	Update — same 422 model-error and credentialed-write 503 contract as create.
DELETE	…/git_remotes/{id}	Destroy — but an archived remote still referenced by changes keeps its row and has its credentials stripped instead: 200 with the meta message "This Git remote cannot be deleted as it is used by a change, its credentials have been removed." A hard delete answers 204.

A remote is also reachable as a sideloaded resource: include=git_remote on the project's templates index or a single-template show carries it in the compound document's included, serialized exactly as the show above — masked credentials and all.

Writes on a server with no encryption keys (503)

Credentials are encrypted before they are stored, so a create or update that supplies a credential (user, password, passphrase or ssh_key_data) on a server with no encryption keys configured cannot be honoured. It answers 503 Service Unavailable with the named detail git remote credentials cannot be stored: no encryption keys are configured on this server — a known, operator-fixable configuration state (set OPSCHAIN_PRIMARY_KEY and OPSCHAIN_KEY_DERIVATION_SALT), deliberately not a 500. Credential-free writes and destroys never encrypt anything, so they never answer this 503.

Attributes

Attribute	Type	Meaning
name	string	The remote's name, unique within the project; how templates reference it (git_remote_name).
url	string	The fetch URL as stored — any userinfo was stripped on write, so exposing it leaks nothing. At most 2048 characters: a longer value is refused by name on create and update (Url is too long (maximum is 2048 characters), a 422 on v1 / invalid_argument with the url field violation on v2); the stored column is unbounded text.
public_url	string, nullable	A display URL override; null when unset. Bounded like url (Public url is too long (maximum is 2048 characters)).
archived	boolean	Archive flag (update-only in effect: create permits it and then ignores it).
disabled	boolean	Disable flag (nullable column, coalesced false on read).
periodic_fetch_interval	integer, nullable	Per-remote override of the background fetch cadence in seconds; null means the remote inherits the default reported in the index meta (project settings override → global settings override → compiled default 900). A supplied null clears the override.
created_at / updated_at	string (ISO8601, 6 fractional digits)	Row timestamps.
user	string, nullable	Masked. "{{hidden}}" when a username credential is stored, null when none is.
ssh_key_data	string, nullable	Masked. "{{hidden}}" when an SSH key is stored, null otherwise.
password	string, nullable	Masked. "{{hidden}}" when a password/passphrase credential is stored and the url is not an SSH url; null otherwise.
passphrase	string, nullable	Masked. The same stored credential presented as a passphrase when the url is an SSH url (explicit ssh:// scheme, or the schemeless scp-like user@host:path form); null otherwise.
credential_ref	string, nullable	The shared git credential this remote references (write-accepted on v1, exposed on v2): fetch/clone resolve the credential at use time, so updating the credential applies to every referencing remote on its next use. Null when the remote stores inline credentials (or none) — a remote never holds both.

Credential redaction semantics

Stored credential values are encrypted at rest and never materialised by this read path at all: the reader selects only a boolean presence per column, and the serializer maps presence to the placeholder {{hidden}} and absence to null. password and passphrase are two views of one stored column, split on whether the URL is SSH. On writes the three-way distinction is load-bearing: an omitted credential key preserves the stored value, while a key supplied as null or "" clears it — so echoing a read payload (all {{hidden}}) back on an update would overwrite credentials; send only the keys you mean to change.

Shared credentials (credential_ref)

Instead of inline values, a write may reference a shared git credential by id — or by name within the remote's scope (the project's own registry, then the global one). The referenced credential must live at or above the remote's node: its project, or the global registry; another project's credential is refused. A write carrying both a credential_ref and inline credential values (URL userinfo included) is refused (Credential ref cannot be combined with inline credentials - supply one or the other); supplying a reference clears any stored inline values (the remote flips to the reference), and supplying inline values while a reference is in place is refused until the reference is cleared (credential_ref: "") in the same write. The reverse migration is the ExtractGitRemoteCredential action — see opschain docs resources/git_credential.

Relationships and links

Name	Meaning
project	To-one project (the owning project).
links.self	/api/projects/<code>/git_remotes/<id>.
links.project	/api/projects/<code>.

The v2 service — GitRemoteService

ListGitRemotes / GetGitRemote (by id or name) / CreateGitRemote / UpdateGitRemote / DeleteGitRemote carry this surface typed, with the same {{hidden}} credential masking, the default_periodic_fetch_interval meta, the credentials-removed delete arm (which also clears a credential_ref), the keyless-write 503 typed as unavailable + ERROR_REASON_SERVER_NOT_CONFIGURED, and credential_ref on the payloads and writes. See opschain docs api-v2.

Related pages

• opschain docs resources/template — templates pin a git remote by name.
• opschain docs resources/git_credential — the shared credential registry remotes reference via credential_ref.