From 39df9a204fa2d14866e09136ca5dbb1dec93bc34 Mon Sep 17 00:00:00 2001
From: Miguel Lozano <miguel@developmi.com>
Date: Tue, 27 Oct 2026 23:17:11 -0500
Subject: [PATCH] fix(ingress): provide actionable guidance on GHCR
 authentication failure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

-
    roles/L4_networking/caddy/tasks/caddy.yml: Capture docker_login result without failing abruptly or leaking credentials; add an explicit
    failure task displaying actionable troubleshooting instructions (referencing vault_github_token, secrets.sops.yml, and read:packages scope)
    when GHCR authentication fails.
---
 roles/L4_networking/caddy/tasks/caddy.yml | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/roles/L4_networking/caddy/tasks/caddy.yml b/roles/L4_networking/caddy/tasks/caddy.yml
index e52f1b0..dcd68e1 100644
--- a/roles/L4_networking/caddy/tasks/caddy.yml
+++ b/roles/L4_networking/caddy/tasks/caddy.yml
@@ -374,8 +374,20 @@
         username: "{{ github_username }}"
         password: "{{ vault_github_token }}"
         reauthorize: true
+      register: _ghcr_login
+      failed_when: false
       no_log: true
 
+    - name: Fail with actionable guidance if GHCR login fails
+      ansible.builtin.fail:
+        msg: >-
+          GHCR authentication failed for user '{{ github_username }}'.
+          Verify that 'vault_github_token' in inventory/group_vars/all/secrets.sops.yml:
+          1. Is a valid, unexpired GitHub Personal Access Token (classic or fine-grained).
+          2. Has the 'read:packages' permission scope enabled.
+          3. Has organization/repository access granted for 'developmi/caddy-waf' if using fine-grained PAT.
+      when: _ghcr_login.failed | default(false)
+
     - name: Pre-pull Caddy image before verification
       community.docker.docker_image:
         name: "{{ caddy_image }}"