Git credential helper

The credential helper connects git to District. It issues a READ_WRITE token that is valid for one git operation, through git's credential-helper protocol. The machine stores no long-lived git token. These commands take no environment flag: the helper reads the environment from the remote URL, not from the environment that the last district login recorded.

district git-credential install

district git-credential install [--dangerously-allow-worktree]

Registers the helper for each Artifacts host. Run the command once per machine, after the first district login. For each host it writes two values into the global git configuration:

credential.https://<host>.helper            (reset, then the absolute helper command)
credential.https://<host>.useHttpPath true

The reset is an empty first value. Without it, a system-level helper such as macOS osxkeychain runs first, caches the short-lived token on store, and returns the expired token on the next operation. Artifacts then answers 403, not 401, so git does not ask this helper again, and every operation fails until the cached entry is removed by hand. The command is idempotent: the unset-then-add sequence produces the same two values on every run.

The helper command contains absolute paths, because an IDE git client starts with a minimal environment where PATH and shell aliases are absent.

Before it writes anything, the command runs the composed helper through sh -c with the store operation, PATH set to /usr/bin:/bin, and the temporary directory as the working directory. These are the conditions git uses. A non-zero exit writes no git configuration and reports the exit code and the helper's own stderr.

The command refuses to run from a linked git worktree. The installed helper command contains that checkout's absolute entry path, and git reads it from the global configuration for every repository. Removing the worktree would prevent authentication for every Artifacts remote. --dangerously-allow-worktree writes it anyway.

Flags

Output

$ district git-credential install

A failed probe prints the exit code and the helper's stderr. The git configuration keeps the values it had before the run.

Exit codes

district git-credential status

district git-credential status

Reports, for each Artifacts host, whether the last registered helper answers every repository namespace on that host and whether useHttpPath is true. A helper from an earlier CLI version can decline a namespace. When a helper cannot authenticate, the command prints the namespaces it cannot answer, the configured value, and the helper's stderr.

Git treats an Artifacts 403 as success rather than as an authentication failure. A clone or a push then fails with no credential prompt when the helper paths no longer resolve. This command reports the unavailable helper.

Output

$ district git-credential status
artifacts.…
  helper: ok
  useHttpPath: true

Exit codes

district git-credential get

district git-credential <get | store | erase>

Git calls these subcommands; people do not. get reads git's description from stdin, selects the environment from the host and the namespace in the path, and answers with a READ_WRITE token in the authtype form for git 2.46 and later, or as a username and password before it.

get reuses a token it issued for the same repository and sign-in until 120 seconds before the token expires. Otherwise it refreshes an access token close to expiry and issues a new token. erase drops the reused token for the repository. store reads stdin and exits 0. An unknown host, protocol, or path declines with exit 1 and no output. Git then uses its own prompt.

Output

$ git push          # git invokes: district git-credential get
$ git clone "$(district repo url my-app)"   # same helper, no token in the URL

Exit codes