Introduction

When Okteto Kubernetes cannot pull a private image from GitHub Container Registry, the failure is usually authentication scope, namespace secret placement, or workload secret reference. The image path may be correct while pull credentials are missing in the effective runtime namespace. A repeatable fix checks token scope, secret creation, and deployment wiring in that order.

Verify Registry Credentials and Image Path

Start with the basics:

• image exists in GHCR with expected tag
• account or token has package read permissions
• image reference uses correct owner and repository path

A typical private image reference looks like:

ghcr.io/org-or-user/image-name:tag

If token scope is wrong, pull fails even when docker login appears to work locally for other registries.

Create Pull Secret in the Correct Namespace

Kubernetes secrets are namespace-scoped. If deployment runs in dev, secret must be in dev.

1kubectl create secret docker-registry ghcr-secret \
2  --docker-server=ghcr.io \
3  --docker-username=GITHUB_USER \
4  --docker-password=GITHUB_TOKEN \
5  --namespace=dev
6
7kubectl get secret ghcr-secret -n dev

Using personal access token is common, but for production use short-lived or managed credentials where possible.

Wire Secret to Pod Pull Flow

Secret existence alone is not enough. It must be referenced by pod template or service account used by workload.

1apiVersion: apps/v1
2kind: Deployment
3metadata:
4  name: api
5  namespace: dev
6spec:
7  replicas: 1
8  selector:
9    matchLabels:
10      app: api
11  template:
12    metadata:
13      labels:
14        app: api
15    spec:
16      imagePullSecrets:
17        - name: ghcr-secret
18      containers:
19        - name: api
20          image: ghcr.io/org/private-image:1.2.3
21          imagePullPolicy: IfNotPresent

If imagePullSecrets is missing, Kubernetes attempts anonymous pull and receives unauthorized errors.

Service Account Strategy for Multiple Workloads

For many deployments in same namespace, attach pull secret to a service account so each deployment does not need repeated config.

kubectl patch serviceaccount default -n dev \
  -p '{"imagePullSecrets": [{"name": "ghcr-secret"}]}'

Then ensure workloads use that service account intentionally.

This reduces duplication and lowers chance of missing secret references in new manifests.

Use Pod Events for Root-Cause Accuracy

Always inspect pod events before changing manifests repeatedly.

kubectl describe pod <pod-name> -n dev
kubectl get events -n dev --sort-by=.metadata.creationTimestamp

Events usually reveal whether failure is:

• unauthorized or forbidden
• image not found
• DNS or network failure
• rate-limit or timeout

Accurate diagnosis prevents unnecessary credential rotation when issue is actually wrong image tag.

Okteto-Specific Considerations

In Okteto, context and namespace selection can shift between personal and shared environments. Verify active namespace before creating secrets.

Also check whether Okteto deployment config overrides image fields or service accounts. Effective runtime config may differ from base Kubernetes manifests.

A quick verification step after deploy:

kubectl get pod <pod-name> -n dev -o yaml | grep -A3 imagePullSecrets

This confirms what the running pod template actually references.

Credential Rotation and Security Hygiene

Treat registry credentials as rotating infrastructure secrets:

• rotate tokens on schedule
• avoid hardcoding tokens in repository manifests
• document who owns rotation and incident response
• validate pull success after each rotation window

For compliance-heavy environments, keep audit logs of secret updates and deployment rollouts tied to credential changes.

Common Pitfalls

Creating secret in wrong namespace is one of the most common mistakes.

Using token without package read scope causes repeated unauthorized errors.

Forgetting imagePullSecrets reference in workload makes valid secret unused.

Debugging only manifest files without checking pod events slows root cause discovery.

Summary

• Private GHCR pulls in Okteto require valid scoped credentials and correct namespace wiring.
• Create pull secret where workload runs, then reference it explicitly.
• Use service account binding for consistent multi-workload behavior.
• Diagnose pull failures from pod events before making random changes.
• Manage token rotation as part of normal cluster operations.