Git Credentials

🚀Git Credential Policy

Stable

Keep native Git authoritative and optionally supply external HTTPS tokens to container pushes.

Command[tool.custy.git.credentials]

📦Category

Git Configuration

🚀Quick Command

[tool.custy.git.credentials]

---

native firstexternal secretsDocker

---

Recommended configuration

Terminal

toml

[tool.custy.git.credentials]
mode = "native"
container_only = true
source_order = ["file", "environment"]
interactive_fallback = true
fail_non_interactive = true

[tool.custy.git.credentials.github]
enabled = false
username = "x-access-token"
token_file = "github.token"
token_env = "CUSTY_GITHUB_TOKEN"

[tool.custy.git.credentials.gitlab]
enabled = false
username = "oauth2"
token_file = "gitlab.token"
token_env = "CUSTY_GITLAB_TOKEN"

⚠️Never put a token in TOML

These tables describe where Custy may find a token. They never contain the token value. Prefer custy configure credentials over manual secret handling.

Policy Properties

📋Properties

Property	Type	Description	Default	Required
mode	native | auto	native disables Custy's fallback. auto allows enabled sources after normal Git authentication.	native	No
container_only	Boolean	Restrict managed fallback to a container so local credential-manager sessions remain unchanged.	true	No
source_order	String array	Search missing sources in order. A malformed present source is an error, not a fallback condition.	[file, environment]	No
interactive_fallback	Boolean	Allow Git's normal username/PAT prompt when the process has an interactive terminal and no managed token resolved.	true	No
fail_non_interactive	Boolean	Disable terminal prompts when they cannot be answered, preventing CI and detached-container hangs.	true	No

Provider Properties

📋Properties

Property	Type	Description	Default	Required
enabled	Boolean	Opt one supported provider into managed fallback.	false	No
username	String	Non-secret HTTPS username. Defaults to x-access-token for GitHub and oauth2 for GitLab.	Provider default	No
token_file	Path string	External filename under the credential root, or an approved absolute path outside the target project.	github.token / gitlab.token	No
token_env	Environment name	Variable read only when environment is included in source_order and provider fallback is active.	CUSTY_GITHUB_TOKEN / CUSTY_GITLAB_TOKEN	No

Behavior matrix

mode	container_only	Local execution	Container execution
native	true or false	Native Git only	Native Git only
auto	true	Native Git only	Native Git, then enabled fallback
auto	false	Native Git, then enabled fallback	Native Git, then enabled fallback

External credential root

Runtime	Default
Windows	%LOCALAPPDATA%\Custy\credentials
Linux	$XDG_DATA_HOME/custy/credentials or ~/.local/share/custy/credentials
Docker	/run/secrets/custy

CUSTY_CREDENTIALS_DIR overrides the root. Relative overrides resolve from the user home, not the project. Custy rejects paths within the target project.

Docker bind-mount mapping

On Windows CMD, this argument maps one persistent host directory to Custy's container credential root:

Terminal

bash

-v "%LOCALAPPDATA%Custycredentials:/run/secrets/custy"

Host path	Container path	Meaning
%LOCALAPPDATA%\Custy\credentials\github.token	/run/secrets/custy/github.token	The same mounted GitHub token file
%LOCALAPPDATA%\Custy\credentials\gitlab.token	/run/secrets/custy/gitlab.token	The same mounted GitLab token file

Use a writable mount for configure credentials set. Add :ro for status, testing, and push after the file exists. Without this mount, /run/secrets/custy lives only in the container and is deleted with a --rm container.

Status interpretation

Column	Meaning
Enabled	Provider policy stored in the project’s config.toml
Token file	Availability and validation of the external file in this process
Environment	Availability of the named token variable in this process

The last two columns describe alternative runtime sources. For example, Enabled: yes, Token file: valid, and Environment: missing is a healthy file-backed configuration.

Runtime source behavior

Runtime state	Behavior
Valid file found first	Use the file; an absent environment variable is irrelevant
File missing, environment available	Continue to the environment source
No managed source, interactive TTY allowed	Give native Git the terminal for a username/PAT or SSH prompt
No managed source, no usable TTY	Fail without waiting when fail_non_interactive = true
Malformed existing source	Stop with an actionable validation error

Resolution Rules

1. Dry-run stops before token reads or remote contact.
2. native mode stops at normal Git/SSH behavior.
3. container_only = true stops managed fallback outside a container.
4. Only exact supported HTTPS hosts are eligible.
5. Git's existing helpers run before the per-command Custy helper.
6. A missing file tries the next source; an invalid existing source stops.
7. An interactive prompt may remain available. Custy gives Git direct terminal ownership so the prompt stays visible and usable.
8. Non-interactive execution fails rather than hanging when the safeguard is enabled.

Continue

🚀Related Commands

Commands commonly used together with this command.

Configure Credentials

Use hidden input and focused provider commands.

Docker

Mount protected files or pass environment variables to a container.

Push Troubleshooting

Interpret authentication and remote failures.

Git Remotes

Keep authentication policy separate from destination selection.