feat: add git:auth-status to check netrc match

Adds `git:auth-status HOST [USERNAME] [PASSWORD]` which exits 0 when the
configured `.netrc` entry matches the requested state and 1 otherwise,
allowing external tooling to detect whether `git:auth` would change
anything without reading `$DOKKU_ROOT/.netrc` directly. Both `git:auth`
and `git:auth-status` now also accept the password via `STDIN`.

docs/deployment/methods/git.md

@@ -6,6 +6,7 @@
 ```
 git:allow-host <host>                             # Adds a host to known_hosts
 git:auth <host> [<username> <password>]           # Configures netrc authentication for a given git server
+git:auth-status <host> [<username> <password>]    # Reports whether the netrc entry matches the requested state
 git:from-archive [--archive-type ARCHIVE_TYPE] <app> <archive-url> [<git-username> <git-email>] # Updates an app's git repository with a given archive file
 git:from-image [--build-dir DIRECTORY] <app> <docker-image> [<git-username> <git-email>] # Updates an app's git repository with a given docker image
 git:generate-deploy-key                           # Generates a deploy ssh key
@@ -191,6 +192,34 @@ dokku git:auth github.com
 
 For syncing to a private repository stored on a remote Git product such as GitHub or GitLab, Dokku's recommendation is to use a personal access token on a bot user where possible. Please see your service's documentation for information regarding the recommended best practices.
 
+The password for `git:auth` may also be provided over `STDIN` to avoid placing it on the command line:
+
+```shell
+# pipe the password into git:auth
+echo "personal-access-token" | dokku git:auth github.com username
+```
+
+#### Checking the configured auth state
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+The `git:auth-status` command reports whether the configured `netrc` entry matches a desired state without exposing the underlying file. It exits `0` when the configured state matches and `1` otherwise. This allows external tooling such as configuration management systems to perform idempotent updates without reading `$DOKKU_ROOT/.netrc` directly.
+
+```shell
+# check whether github.com is configured with the expected credentials
+dokku git:auth-status github.com username personal-access-token
+
+# check whether no credentials are configured for github.com
+dokku git:auth-status github.com
+```
+
+As with `git:auth`, the password may be provided via `STDIN`:
+
+```shell
+echo "personal-access-token" | dokku git:auth-status github.com username
+```
+
 ### Allowing remote repository hosts
 
 By default, the Dokku host may not have access to a server containing the remote repository. This can be initialized via the `git:allow-host` command.

plugins/git/help-functions

@@ -29,6 +29,7 @@ fn-help-content() {
   cat <<help_content
     git:allow-host <host>, Adds a host to known_hosts
     git:auth <host> [<username> <password>], Configures netrc authentication for a given git server
+    git:auth-status <host> [<username> <password>], Reports whether the netrc entry matches the requested state (exit 0 if matches)
     git:from-archive <app> <archive-url> [<git-username> <git-email>], Updates an app's git repository with a given archive file
     git:from-image <app> <docker-image> [<git-username> <git-email>], Updates an app's git repository with a given docker image
     git:load-image <app> <docker-image> [<git-username> <git-email>], Updates an app's git repository with a docker image loaded from stdin

plugins/git/internal-functions

@@ -76,6 +76,8 @@ cmd-git-auth() {
   declare HOST="$1" USERNAME="$2" PASSWORD="$3"
   [[ -z "$HOST" ]] && dokku_log_fail "Please supply a git host"
 
+  PASSWORD="$(fn-git-auth-read-password "$USERNAME" "$PASSWORD")"
+
   if [[ -n "$USERNAME" ]] && [[ -z "$PASSWORD" ]]; then
     dokku_log_fail "Missing password for netrc auth entry"
   fi
@@ -91,6 +93,42 @@ cmd-git-auth() {
   netrc set "$HOST" "$USERNAME" "$PASSWORD"
 }
 
+cmd-git-auth-status() {
+  declare desc="reports whether netrc authentication matches the requested state"
+  local cmd="git:auth-status"
+  [[ "$1" == "$cmd" ]] && shift 1
+  declare HOST="$1" USERNAME="$2" PASSWORD="$3"
+  [[ -z "$HOST" ]] && dokku_log_fail "Please supply a git host"
+
+  PASSWORD="$(fn-git-auth-read-password "$USERNAME" "$PASSWORD")"
+
+  if [[ -n "$USERNAME" ]] && [[ -z "$PASSWORD" ]]; then
+    dokku_log_fail "Missing password for netrc auth entry"
+  fi
+
+  local current
+  current="$(netrc get "$HOST" 2>/dev/null)" || current=""
+
+  if [[ -z "$USERNAME" ]]; then
+    [[ -z "$current" ]] && return 0
+    return 1
+  fi
+
+  [[ "$current" == "${USERNAME}:${PASSWORD}" ]] && return 0
+  return 1
+}
+
+fn-git-auth-read-password() {
+  declare desc="reads a netrc password from stdin when not provided as an argument"
+  declare USERNAME="$1" PASSWORD="$2"
+
+  if [[ -n "$USERNAME" ]] && [[ -z "$PASSWORD" ]] && [[ -p /dev/stdin ]]; then
+    IFS= read -r PASSWORD || true
+  fi
+
+  echo -n "$PASSWORD"
+}
+
 cmd-git-load-image() {
   declare desc="updates an app's git repository with a docker image loaded from stdin"
   local cmd="git:load-image"

plugins/git/subcommands/auth-status

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+source "$PLUGIN_AVAILABLE_PATH/git/internal-functions"
+set -eo pipefail
+[[ $DOKKU_TRACE ]] && set -x
+
+cmd-git-auth-status "$@"

tests/unit/git_3.bats

@@ -93,6 +93,71 @@ teardown() {
   echo "status: $status"
   assert_success
   assert_output_contains "Setting netrc auth entry for host github.com"
+
+  run /bin/bash -c "printf 'piped-password' | dokku git:auth github.com piped-username"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+  assert_output_contains "Setting netrc auth entry for host github.com"
+
+  run /bin/bash -c "grep piped-username /home/dokku/.netrc"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+  assert_output_contains "piped-password"
+}
+
+@test "(git) git:auth-status" {
+  run /bin/bash -c "dokku git:auth-status"
+  echo "output: $output"
+  echo "status: $status"
+  assert_failure
+
+  run /bin/bash -c "dokku git:auth-status github.com"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku git:auth github.com username password"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku git:auth-status github.com"
+  echo "output: $output"
+  echo "status: $status"
+  assert_failure
+
+  run /bin/bash -c "dokku git:auth-status github.com username password"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "dokku git:auth-status github.com username wrong-password"
+  echo "output: $output"
+  echo "status: $status"
+  assert_failure
+
+  run /bin/bash -c "dokku git:auth-status github.com other-username password"
+  echo "output: $output"
+  echo "status: $status"
+  assert_failure
+
+  run /bin/bash -c "dokku git:auth-status github.com username"
+  echo "output: $output"
+  echo "status: $status"
+  assert_failure
+  assert_output_contains "Missing password for netrc auth entry"
+
+  run /bin/bash -c "printf 'password' | dokku git:auth-status github.com username"
+  echo "output: $output"
+  echo "status: $status"
+  assert_success
+
+  run /bin/bash -c "printf 'wrong-password' | dokku git:auth-status github.com username"
+  echo "output: $output"
+  echo "status: $status"
+  assert_failure
 }
 
 @test "(git) git:sync new [errors]" {