opschain git-remotes create

Included from Basic tier

opschain git-remotes create <project> [-f <file.yaml>] [--name <name> --url <url>] [--credential-ref <id|name> | credential flags]

Creates a Git remote the project's changes and templates can build from. A remote needs at least a name (unique within the project) and a repository URL; both can come from flags or from the -f file, with flags winning over file values.

Credential handling

A remote authenticates in one of two ways — a shared credential reference (recommended) or inline credentials — and never both.

Shared credential (--credential-ref <id|name>). Point the remote at a credential in the shared registry (opschain git-credentials): the project's own, or a global one, by id or by name (a project credential shadows a global one of the same name). The reference resolves at use time, so rotating the credential once (opschain git-credentials update) applies to every referencing remote on its next fetch. Another project's credential is refused by the server. The same value may come from the -f file as credential_ref — it is a reference, not a secret.

Inline credentials. They never travel through argv, and never live in definition files — the server stores them encrypted and never returns their values (show and list report them only as set or unset).

• HTTP(S) remotes authenticate with --username plus a password or token: --password-env <VAR> names an environment variable holding the value, or --password-prompt reads it without echo (a plain line read when stdin is piped, so scripts keep working). The two are mutually exclusive.
• SSH remotes (ssh:// or scp-like user@host:path URLs) authenticate with --ssh-key-file <path> — the private key file, read from disk and sent as the key's contents — optionally protected by a passphrase from --passphrase-env <VAR>. --username supplies the SSH user when the URL does not carry one.

Exclusivity. A reference beside any inline credential flag (or a user key in the file) is refused before the call; a reference the server cannot combine (userinfo in the URL, say) is refused by the server with Credential ref cannot be combined with inline credentials - supply one or the other.

Flags

Flag	Meaning
-f, --file <file.yaml>	Strict YAML definition of the non-secret attributes. Keys: name, url, public_url, user, periodic_fetch_interval, credential_ref. An unknown key is refused by name; a credential key (password, passphrase, ssh_key_data) is refused with a pointer at the credential flags.
--credential-ref <id|name>	Reference a shared git credential (the project's own, or a global one) instead of inline credentials. Mutually exclusive with the inline flags.
--name <name>	The remote's name (unique within the project). Required here or in -f.
--url <url>	The Git repository URL (https://, ssh:// or scp-like user@host:path). Required here or in -f.
--public-url <url>	Credential-free URL shown in logs and the GUI instead of the real URL.
--fetch-interval <seconds>	Periodic fetch interval (60–86400). Only sent when the flag is given; omit to inherit the project/global default.
--username <user>	Username for the remote (HTTP(S) basic auth, or the SSH user).
--password-env <VAR>	Name of an environment variable holding the HTTP(S) password or token — never the value itself.
--password-prompt	Prompt for the HTTP(S) password or token without echo.
--passphrase-env <VAR>	Name of an environment variable holding the SSH key's passphrase.
--ssh-key-file <path>	Path to the SSH private key.

Exit codes

Code	Meaning
0	Created.
1	The server refused the create (validation — a blank or over-long URL (more than 2048 characters), an invalid --public-url, a duplicate name, an unknown or out-of-scope --credential-ref), or the SSH key file could not be read.
2	Usage error — missing name/url, credential flag misuse (a reference beside inline credentials included), bad -f file, no server target.

Named errors

• a git remote needs a name and a url — pass --name and --url (or supply them in -f) — 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 needs a shared credential id or name — an empty reference on create (exit 2).
• Credential ref must reference a shared credential at the Git remote's project or the global registry / Credential ref is invalid — the server's scope and existence rules (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 — a secret key in the -f file (exit 2).
• no password provided (pipe it on stdin, or run from a terminal) — the prompt read nothing (exit 2).
• reading the SSH key file: <error> — exit 1.
• git remotes live on a server's projects — pass --server <url> or 'opschain context use <name>' — no server target (exit 2).

Examples

A remote on a shared credential (the recommended form — one registry entry, rotated once for every remote; github-ci was stored in the project's registry with opschain git-credentials create, opschain docs cli/git-credentials-create):

opschain git-remotes create demo --name origin \
  --url https://github.com/acme/demo-config.git --credential-ref github-ci
created git remote demo/origin (0199a2c4-…)

Token-authenticated HTTPS remote with inline credentials, token from the environment:

opschain git-remotes create demo --name origin \
  --url https://github.com/acme/demo-config.git \
  --username ci-bot --password-env GIT_TOKEN
created git remote demo/origin (0199a2c4-…)

SSH remote with a passphrase-protected key:

opschain git-remotes create demo --name origin \
  --url git@github.com:acme/demo-config.git \
  --ssh-key-file ~/.ssh/opschain_deploy --passphrase-env KEY_PASSPHRASE

Non-secret attributes from a file, prompting for the token:

opschain git-remotes create demo -f remote.yaml --password-prompt

Related settings

• periodic_fetch_interval left unset inherits the project/global Git fetch default from the server's settings tree.

See also

• opschain docs cli/git-credentials — the shared registry a reference names.
• opschain docs cli/git-remotes-update — replace credentials, move to or off a reference, or repoint within the same repository.
• opschain docs cli/templates-create — templates pin versions of a remote's repository.
• opschain learn 3.3 — the guided tour.