ci: add manual workflow to validate DOCKERHUB_TOKEN before a build

.github/workflows/dockerhub-credential-check.yml

@@ -0,0 +1,50 @@
+name: Docker Hub Credential Check
+
+# Manual workflow that proves DOCKERHUB_USERNAME / DOCKERHUB_TOKEN are valid
+# for the readme-push API path before triggering an expensive build. Issue #714
+# rotated the secret because the readme push was returning Forbidden; this lets
+# whoever rotates next confirm the new value works in seconds, without pushing
+# an image.
+#
+# Validates two paths: registry login (used by docker/login-action in the
+# build workflows) and the Docker Hub API (used by peter-evans/dockerhub-description
+# to PATCH the repo description). A token can pass the first and fail the
+# second, which is exactly the failure mode that prompted #714.
+#
+# The API check writes the current description back to itself via a no-op PATCH
+# so it actually exercises the write/delete scope peter-evans uses; a read-only
+# token would 200 on a GET but 403 here. Side effect: bumps Docker Hub's
+# last-modified timestamp on the repo (the same side effect the real readme
+# push already produces every time it runs, so nothing novel).
+
+on:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Validate registry login
+        uses: docker/login-action@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.5'
+
+      - name: Install Task
+        uses: arduino/setup-task@v2
+
+      - name: Validate Docker Hub API auth
+        env:
+          DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+          DOCKERHUB_TOKEN: ${{ secrets.DOCKERHUB_TOKEN }}
+        working-directory: tools/release
+        run: task ci:check-dockerhub-credential

tools/release/Taskfile.yml

@@ -153,6 +153,14 @@ tasks:
         php bin/lint-versions.php
         --repo={{shellQuote (default "../.." .ROTATE_REPO)}}
 
+  ci:check-dockerhub-credential:
+    desc: Smoke-test DOCKERHUB_USERNAME / DOCKERHUB_TOKEN against the readme-push API path
+    deps: [setup]
+    cmds:
+      - >-
+        php bin/check-dockerhub-credential.php
+        {{if .REPOSITORY}}--repository={{shellQuote .REPOSITORY}}{{end}}
+
   release:verify-tag:
     desc: Verify a release tag is annotated and well-formed per #664 spec
     requires:

tools/release/bin/check-dockerhub-credential.php

@@ -0,0 +1,61 @@
+#!/usr/bin/env php
+<?php
+
+/**
+ * Validate DOCKERHUB_USERNAME / DOCKERHUB_TOKEN against the Docker Hub API
+ * path that peter-evans/dockerhub-description uses.
+ *
+ * Manual smoke test invoked from the dockerhub-credential-check workflow.
+ * Exits non-zero on failure with a `::error::` line; on success emits a
+ * `::notice::` line.
+ *
+ * @package   openemr-devops
+ * @link      https://www.open-emr.org
+ * @author    Michael A. Smith <michael@opencoreemr.com>
+ * @copyright Copyright (c) 2026 OpenCoreEMR Inc.
+ * @license   https://github.com/openemr/openemr-devops/blob/master/LICENSE GNU General Public License 3
+ */
+
+declare(strict_types=1);
+
+require dirname(__DIR__) . '/vendor/autoload.php';
+
+use OpenEMR\Release\DockerHubCredentialChecker;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Console\SingleCommandApplication;
+
+(new SingleCommandApplication())
+    ->setName('check-dockerhub-credential')
+    ->setDescription('Validate DOCKERHUB_USERNAME / DOCKERHUB_TOKEN for the readme-push API path')
+    ->addOption(
+        'repository',
+        null,
+        InputOption::VALUE_REQUIRED,
+        'Docker Hub repository (owner/name)',
+        'openemr/openemr',
+    )
+    ->setCode(function (InputInterface $input, OutputInterface $output): int {
+        $username = getenv('DOCKERHUB_USERNAME');
+        $token = getenv('DOCKERHUB_TOKEN');
+        if (!is_string($username) || $username === '') {
+            $output->writeln('::error::DOCKERHUB_USERNAME env var is required');
+            return 1;
+        }
+        if (!is_string($token) || $token === '') {
+            $output->writeln('::error::DOCKERHUB_TOKEN env var is required');
+            return 1;
+        }
+        /** @var string $repository */
+        $repository = $input->getOption('repository');
+        if (preg_match('#^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9._-]+$#', $repository) !== 1) {
+            $output->writeln('::error::--repository must match owner/name (alphanumeric, dot, underscore, dash).');
+            return 1;
+        }
+
+        $result = (new DockerHubCredentialChecker())->check($username, $token, $repository);
+        $output->writeln($result->toGithubActionsLine());
+        return $result->isOk() ? 0 : 1;
+    })
+    ->run();

tools/release/composer.json

@@ -5,6 +5,7 @@
     "license": "GPL-2.0-or-later",
     "require": {
         "php": "^8.5",
+        "ext-curl": "*",
         "ext-mbstring": "*",
         "nikic/php-parser": "^5.0",
         "symfony/console": "^7.0",

tools/release/src/DockerHubCredentialCheckResult.php

@@ -0,0 +1,162 @@
+<?php
+
+/**
+ * Outcome of a Docker Hub credential check.
+ *
+ * @package   openemr-devops
+ * @link      https://www.open-emr.org
+ * @author    Michael A. Smith <michael@opencoreemr.com>
+ * @copyright Copyright (c) 2026 OpenCoreEMR Inc.
+ * @license   https://github.com/openemr/openemr-devops/blob/master/LICENSE GNU General Public License 3
+ */
+
+declare(strict_types=1);
+
+namespace OpenEMR\Release;
+
+final readonly class DockerHubCredentialCheckResult
+{
+    public DockerHubCredentialCheckStatus $status;
+    public string $repository;
+    public ?int $httpStatus;
+    public ?string $detail;
+
+    public function __construct(
+        DockerHubCredentialCheckStatus $status,
+        string $repository,
+        ?int $httpStatus = null,
+        ?string $detail = null,
+    ) {
+        // Defensively scrub CR/LF from caller-controlled strings before they
+        // ever get formatted into a `::error::` / `::notice::` line. The
+        // workflow-command syntax is line-based; an embedded newline could
+        // inject a second command. Belt-and-braces — the bin layer also
+        // validates repository against an owner/name pattern up front.
+        $this->status = $status;
+        $this->repository = $this->scrubLineBreaks($repository);
+        $this->httpStatus = $httpStatus;
+        $this->detail = $detail !== null ? $this->scrubLineBreaks($detail) : null;
+    }
+
+    private function scrubLineBreaks(string $value): string
+    {
+        return strtr($value, ["\r" => ' ', "\n" => ' ']);
+    }
+
+    /**
+     * Map raw HTTP statuses from Docker Hub's login + repository read +
+     * repository write probes to a result. Pure: no network. Tested directly.
+     *
+     * - $loginStatus is the POST /v2/users/login/ HTTP status (null if the
+     *   request itself failed at the transport layer)
+     * - $jwt is the token extracted from the login response (null if the
+     *   response was unparseable JSON or missing the token field)
+     * - $readStatus is the GET /v2/repositories/<repo>/ status (null if the
+     *   step was not reached)
+     * - $descriptionsParsed is whether the GET response body was usable JSON
+     *   with the expected fields (null if read step not reached)
+     * - $writeStatus is the no-op PATCH /v2/repositories/<repo>/ status
+     *   (null if the step was not reached)
+     */
+    public static function interpret(
+        string $repository,
+        ?int $loginStatus,
+        ?string $jwt,
+        ?int $readStatus,
+        ?bool $descriptionsParsed,
+        ?int $writeStatus,
+    ): self {
+        if ($loginStatus === null) {
+            return new self(DockerHubCredentialCheckStatus::NETWORK_ERROR, $repository);
+        }
+        if (in_array($jwt, [null, '', 'null'], true)) {
+            return self::fromAuthFailure($repository, $loginStatus);
+        }
+        if ($readStatus === null) {
+            return new self(DockerHubCredentialCheckStatus::NETWORK_ERROR, $repository);
+        }
+        if ($readStatus !== 200 || $descriptionsParsed !== true) {
+            return self::fromAccessFailure($repository, $readStatus);
+        }
+        if ($writeStatus === null) {
+            return new self(DockerHubCredentialCheckStatus::NETWORK_ERROR, $repository);
+        }
+        return self::fromWriteStatus($repository, $writeStatus);
+    }
+
+    public function isOk(): bool
+    {
+        return $this->status === DockerHubCredentialCheckStatus::OK;
+    }
+
+    /**
+     * Format as a single GitHub-Actions workflow command line
+     * (`::error::…` or `::notice::…`).
+     */
+    public function toGithubActionsLine(): string
+    {
+        return match ($this->status) {
+            DockerHubCredentialCheckStatus::OK => sprintf(
+                '::notice::Credential is valid for %s (read + no-op write confirmed).',
+                $this->repository,
+            ),
+            DockerHubCredentialCheckStatus::INVALID_CREDENTIAL =>
+                '::error::Login failed (HTTP ' . $this->httpStatusOrUnknown()
+                . ') — DOCKERHUB_USERNAME / DOCKERHUB_TOKEN appear invalid.',
+            DockerHubCredentialCheckStatus::INSUFFICIENT_SCOPE => sprintf(
+                '::error::Login succeeded but the token lacks required scope on %s (HTTP %s). '
+                . 'Verify R/W/D scope on this repository.',
+                $this->repository,
+                $this->httpStatusOrUnknown(),
+            ),
+            DockerHubCredentialCheckStatus::UNEXPECTED_RESPONSE => sprintf(
+                '::error::Unexpected response from Docker Hub API for %s (HTTP %s). %s',
+                $this->repository,
+                $this->httpStatusOrUnknown(),
+                $this->detail ?? 'Re-run, check status.docker.com, then re-evaluate.',
+            ),
+            DockerHubCredentialCheckStatus::NETWORK_ERROR => sprintf(
+                '::error::Could not reach Docker Hub API for %s. %s',
+                $this->repository,
+                $this->detail ?? 'Re-run, check status.docker.com, then re-evaluate.',
+            ),
+        };
+    }
+
+    private static function fromAuthFailure(string $repository, int $loginStatus): self
+    {
+        return match (true) {
+            in_array($loginStatus, [401, 403], true) =>
+                new self(DockerHubCredentialCheckStatus::INVALID_CREDENTIAL, $repository, $loginStatus),
+            default =>
+                new self(DockerHubCredentialCheckStatus::UNEXPECTED_RESPONSE, $repository, $loginStatus),
+        };
+    }
+
+    private static function fromAccessFailure(string $repository, int $readStatus): self
+    {
+        return match (true) {
+            in_array($readStatus, [401, 403], true) =>
+                new self(DockerHubCredentialCheckStatus::INSUFFICIENT_SCOPE, $repository, $readStatus),
+            default =>
+                new self(DockerHubCredentialCheckStatus::UNEXPECTED_RESPONSE, $repository, $readStatus),
+        };
+    }
+
+    private static function fromWriteStatus(string $repository, int $writeStatus): self
+    {
+        return match (true) {
+            $writeStatus === 200 =>
+                new self(DockerHubCredentialCheckStatus::OK, $repository, 200),
+            in_array($writeStatus, [401, 403], true) =>
+                new self(DockerHubCredentialCheckStatus::INSUFFICIENT_SCOPE, $repository, $writeStatus),
+            default =>
+                new self(DockerHubCredentialCheckStatus::UNEXPECTED_RESPONSE, $repository, $writeStatus),
+        };
+    }
+
+    private function httpStatusOrUnknown(): string
+    {
+        return $this->httpStatus !== null ? (string) $this->httpStatus : '(unknown)';
+    }
+}

tools/release/src/DockerHubCredentialCheckStatus.php

@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * @package   openemr-devops
+ * @link      https://www.open-emr.org
+ * @author    Michael A. Smith <michael@opencoreemr.com>
+ * @copyright Copyright (c) 2026 OpenCoreEMR Inc.
+ * @license   https://github.com/openemr/openemr-devops/blob/master/LICENSE GNU General Public License 3
+ */
+
+declare(strict_types=1);
+
+namespace OpenEMR\Release;
+
+enum DockerHubCredentialCheckStatus: string
+{
+    case OK = 'ok';
+    case INVALID_CREDENTIAL = 'invalid_credential';
+    case INSUFFICIENT_SCOPE = 'insufficient_scope';
+    case UNEXPECTED_RESPONSE = 'unexpected_response';
+    case NETWORK_ERROR = 'network_error';
+}