diff --git a/docs/deployment/methods/git.md b/docs/deployment/methods/git.md index b27371a07..8106a7445 100644 --- a/docs/deployment/methods/git.md +++ b/docs/deployment/methods/git.md @@ -6,6 +6,7 @@ ``` git:allow-host # Adds a host to known_hosts git:auth [ ] # Configures netrc authentication for a given git server +git:auth-status [ ] # Reports whether the netrc entry matches the requested state git:from-archive [--archive-type ARCHIVE_TYPE] [ ] # Updates an app's git repository with a given archive file git:from-image [--build-dir DIRECTORY] [ ] # 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. diff --git a/plugins/git/help-functions b/plugins/git/help-functions index 34d116c51..0ef115c4c 100755 --- a/plugins/git/help-functions +++ b/plugins/git/help-functions @@ -29,6 +29,7 @@ fn-help-content() { cat <, Adds a host to known_hosts git:auth [ ], Configures netrc authentication for a given git server + git:auth-status [ ], Reports whether the netrc entry matches the requested state (exit 0 if matches) git:from-archive [ ], Updates an app's git repository with a given archive file git:from-image [ ], Updates an app's git repository with a given docker image git:load-image [ ], Updates an app's git repository with a docker image loaded from stdin diff --git a/plugins/git/internal-functions b/plugins/git/internal-functions index 18c2f651b..45579882b 100755 --- a/plugins/git/internal-functions +++ b/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" diff --git a/plugins/git/subcommands/auth-status b/plugins/git/subcommands/auth-status new file mode 100755 index 000000000..8c6f9e4ac --- /dev/null +++ b/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 "$@" diff --git a/tests/unit/git_3.bats b/tests/unit/git_3.bats index 8e7119d41..f7563f8a5 100644 --- a/tests/unit/git_3.bats +++ b/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]" {