opschain git-remotes update

Included from Basic tier

opschain git-remotes update <project>/<name> [-f <file.yaml>] [attribute flags] [--credential-ref <id|name>] [credential flags]

Patches a Git remote: only what is supplied is sent, and every unsupplied attribute — stored credentials included — keeps its stored value. At least one of -f, an attribute flag or a credential flag is required.

Two server-side rules worth knowing before reaching for this command:

• The URL can only change host or path while the remote stays on the same repository. Pointing at a different repository means deleting and recreating the remote.
• Credentials are replaced, never read back. The credential flags work exactly as on create — --password-env/--password-prompt for HTTP(S), --ssh-key-file/--passphrase-env for SSH, --username for either — and definition files refuse credential keys.
• A remote references a shared credential or holds inline values, never both. --credential-ref <id|name> flips the remote to a credential from the shared registry (opschain git-credentials — the project's own or a global one) and the server clears its stored inline values; it cannot travel with an inline credential flag (refused before the call). --credential-ref "" clears the reference — and may accompany inline credential flags, which is how a referenced remote moves back to inline values in one write; inline values sent while a reference stands, without clearing it, are refused by the server (Credential ref cannot be combined with inline credentials - supply one or the other). The file key credential_ref carries the same value.

Flags

Flag	Meaning
-f, --file <file.yaml>	Strict YAML definition — every attribute in it is sent. Keys: name, description, url, public_url, user, periodic_fetch_interval, archived, credential_ref, watch_default_branch. Credential keys are refused.
--credential-ref <id|name>	Reference a shared git credential (clears the stored inline values); "" clears the reference. Mutually exclusive with the inline flags unless empty.
--rename <name>	New name for the remote.
--description <text>	New description.
--url <url>	New URL (must stay on the same repository, and be a transport URL — http://, https://, ssh://, git:// or user@host:path — unless the server's security.allow_local_git_remotes admits a path or file://).
--public-url <url>	New credential-free display URL.
--fetch-interval <seconds>	New periodic fetch interval (60–86400). Sent only when the flag is given.
--archived	Archive (true) or unarchive (false) the remote. Sent only when the flag is given, so --archived=false unarchives.
--watch-default-branch	Switch the default-branch ref-move watch on (true) or off (false) — opschain docs resources/git_remote ("Ref-move events"). Sent only when the flag is given, so --watch-default-branch=false opts out.
--username <user>	Replace the stored username.
--password-env <VAR>	Replace the HTTP(S) password/token with the named environment variable's value.
--password-prompt	Replace it with a value read without echo (mutually exclusive with the env form).
--passphrase-env <VAR>	Replace the SSH key passphrase.
--ssh-key-file <path>	Replace the SSH private key with this file's contents.

Exit codes

Code	Meaning
0	Updated — prints updated git remote <project>/<name>.
1	The remote was not found, or the server refused the patch (e.g. a URL pointing at a different repository, a URL that is not a transport URL (Url must be an http(s)://, ssh://, git:// or user@host:path remote), a URL over 2048 characters, an unknown or out-of-scope --credential-ref, inline values while a reference stands).
2	Usage error — nothing supplied, credential flag misuse (a non-empty reference beside inline credentials included), bad -f file, malformed address, no server target.

Named errors

• nothing to update — pass -f, an attribute flag and/or a credential flag — exit 2.
• --credential-ref cannot be combined with inline credentials (--username, --password-env, --password-prompt, --passphrase-env, --ssh-key-file or a user key in -f) — supply one or the other — exit 2.
• Credential ref cannot be combined with inline credentials - supply one or the other — the server, when inline values arrive while a reference stands (exit 1).
• --password-env and --password-prompt are mutually exclusive — exit 2.
• --password-env <VAR>: the environment variable is not set (or empty) — and the --passphrase-env twin — exit 2.
• <file> sets <key> — credentials never live in definition files; use --password-env, --password-prompt, --passphrase-env or --ssh-key-file — exit 2.
• expected <project>/<git-remote-name>, got "<arg>" — exit 2.
• git remote "<name>" not found in project "<project>" — exit 1.

Examples

Rotate an HTTPS token without touching anything else:

opschain git-remotes update demo/origin --password-env NEW_GIT_TOKEN
updated git remote demo/origin

Move a remote onto a shared credential (its inline values are cleared):

opschain git-remotes update demo/origin --credential-ref github-ci

Move it back to inline credentials in one write:

opschain git-remotes update demo/origin --credential-ref "" \
  --username ci-bot --password-env GIT_TOKEN

Move the repository to a new host (same repository):

opschain git-remotes update demo/origin --url https://git.acme.internal/acme/demo-config.git

Archive a remote:

opschain git-remotes update demo/origin --archived

See also

• opschain docs cli/git-credentials-update — rotate a shared credential once for every remote that references it.
• opschain docs cli/git-remotes-show — verify what is set afterwards (credential_ref names the referenced credential's id).
• opschain docs cli/git-remotes-delete — for moving to a different repository.