Support pulling private images via Docker credentials by franzejr · Pull Request #18 · basecamp/once

franzejr · 2026-03-19T10:32:21Z

Deploying apps from private registries (e.g. ghcr.io, GCR, ECR) would fail because image pulls always used anonymous access. I was trying to use it, even on DHH presentation he had an issue with this. This PR adds credential resolution from the local Docker config, so Once can pull private images the same way docker pull does — without any extra configuration from the user, just using the normal login in the machine.

Test Plan

Automated

Run go test ./internal/docker/... — all registry auth tests pass

Manual (private image)

Tag and push a test image to a private registry you have credentials for
(e.g. a private ghcr.io package)
Ensure docker pull <image> works on the machine (confirms credentials
are in ~/.docker/config.json)
Run once deploy with that image — confirm it pulls successfully without
any auth errors

Fallback behaviour

Deploy a public image — confirm it still works (falls back to anonymous
access as before)
Remove or corrupt ~/.docker/config.json — confirm Once falls back
gracefully to anonymous access rather than erroring out

Image pulls always used anonymous access, causing failures for private registries. Users had to work around this manually. Add registry_auth.go which reads ~/.docker/config.json and resolves credentials via credential helpers, credential stores, or inline base64 auth entries. Pass the resolved token to ImagePull via RegistryAuth. Falls back to anonymous access on any error or missing credentials.

franzejr · 2026-03-19T10:35:56Z

@kevinmcconnell I tested this locally, and it worked really well. Would like to hear your thoughts.

Copilot

Pull request overview

This PR adds Docker registry credential resolution so image pulls can authenticate against private registries using the local Docker config (similar to docker pull), and wires that auth into the Docker ImagePull call.

Changes:

Add registry auth resolution from ~/.docker/config.json, including credHelpers, credsStore, and inline auths.
Pass resolved auth token into image.PullOptions.RegistryAuth during image pulls.
Add unit tests covering helper/store/inline paths and error handling.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.

File	Description
internal/docker/registry_auth.go	Implements docker config parsing + credential helper execution + token encoding.
internal/docker/registry_auth_test.go	Adds unit tests for registry host parsing and all credential resolution paths.
internal/docker/application.go	Uses resolved RegistryAuth when pulling images.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

franzejr · 2026-03-19T10:40:49Z

internal/docker/registry_auth.go

+	home, err := os.UserHomeDir()
+	if err != nil {
+		return ""
+	}
+
+	cfg, err := loadDockerConfig(filepath.Join(home, ".docker", "config.json"))
+	if err != nil {
+		return ""
+	}


Addressed in: 47f4d08

franzejr · 2026-03-19T10:46:44Z

internal/docker/registry_auth.go

+	if entry, ok := cfg.Auths[host]; ok && entry.Auth != "" {
+		return authFromInlineEntry(entry.Auth)
+	}


This proposed solution is a bit over-engineering. I simplified the idea and addressed it here: ddf9466

franzejr · 2026-03-19T10:53:09Z

internal/docker/registry_auth.go

+func authFromCredHelper(helper, serverURL string) string {
+	cmd := exec.Command("docker-credential-"+helper, "get")
+	cmd.Stdin = strings.NewReader(serverURL)
+	out, err := cmd.Output()


Over-engineering approach. I addressed the concern in a simpler way: 32cdf8e

internal/docker/registry_auth.go

+type encodedAuthConfig struct {
+	Username string `json:"username,omitempty"`
+	Password string `json:"password,omitempty"`
+}


internal/docker/registry_auth_test.go

+		assert.Equal(t, "inline-user", ac.Username)
+		assert.Equal(t, "inline-pass", ac.Password)
+	})
+


internal/docker/registry_auth_test.go

+	dir := t.TempDir()
+	t.Setenv("HOME", dir)


Credential resolution always read ~/.docker/config.json, ignoring the DOCKER_CONFIG environment variable. Users with a non-default Docker config directory would have Once fall back to anonymous pulls even though docker pull worked correctly for them. Extract dockerConfigPath() which checks DOCKER_CONFIG first and falls back to ~/.docker/config.json, matching Docker's own resolution behaviour. This does not support the legacy ~/.dockercfg format. Supporting it would require additional fallback logic but covers a very small number of users on modern Docker installations.

Direct lookup of cfg.Auths[host] missed entries where docker login stored the key as a full URL (e.g. https://index.docker.io/v1/ instead of docker.io). Affected users would silently fall back to anonymous pulls despite having valid credentials configured. Add authEntryFor which tries an exact match first, then falls back to parsing URL-style keys with url.Parse and comparing the extracted host via canonicalHost, which maps the known Docker Hub aliases to docker.io. This does not handle every possible key format Docker has used historically (e.g. registry-1.docker.io without a scheme). Adding more aliases to canonicalHost is straightforward if other cases emerge.

Copilot

Pull request overview

This PR adds support for pulling images from private registries by resolving credentials from the local Docker config (similar to docker pull) and passing the resulting auth token to Docker’s ImagePull API.

Changes:

Implement Docker registry auth resolution via ~/.docker/config.json / $DOCKER_CONFIG with support for credHelpers, credsStore, and inline auths.
Use the resolved registry auth when pulling application images.
Add unit tests covering host parsing, docker config parsing, inline auth decoding, and credential helper execution paths.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
`internal/docker/registry_auth.go`	Adds credential discovery and encoding logic for Docker registry pulls.
`internal/docker/registry_auth_test.go`	Adds unit tests for config parsing and auth resolution behavior.
`internal/docker/application.go`	Passes resolved `RegistryAuth` into `ImagePull` for app deployments.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

franzejr · 2026-03-19T11:04:45Z

internal/docker/registry_auth.go

+func dockerConfigPath() string {
+	if dir := os.Getenv("DOCKER_CONFIG"); dir != "" {
+		return filepath.Join(dir, "config.json")
+	}
+	home, err := os.UserHomeDir()


Added in: 9d3b3b4

franzejr · 2026-03-19T11:04:40Z

internal/docker/registry_auth.go

+	cfg, err := loadDockerConfig(dockerConfigPath())
+	if err != nil {
+		return ""
+	}


Added in: 9d3b3b4

Credential helpers were called with the bare host (e.g. docker.io), but Docker Hub stores credentials under https://index.docker.io/v1/ — the URL docker login uses. Helpers looking up docker.io would find nothing and fall back to anonymous pulls. Add credHelperServerURL which maps docker.io to the canonical Docker Hub URL and returns the bare host unchanged for all other registries. Other registries could also have legacy URL-keyed entries in their helpers. Those are rare in practice; adding more mappings to credHelperServerURL is straightforward if cases emerge.

Two behaviours introduced in this branch had no end-to-end test coverage: reading config from a DOCKER_CONFIG-specified directory, and falling back to anonymous access when config.json exists but contains invalid JSON. Add subtests in TestRegistryAuthFor for both cases. The DOCKER_CONFIG test also revealed that config.json must be written directly into the directory DOCKER_CONFIG points to, not in a .docker/ subdirectory — which is how Docker itself resolves the path.

Copilot

Pull request overview

This PR adds Docker registry authentication resolution (from local Docker config/credential helpers) so once deploy can pull private images the same way docker pull does, falling back to anonymous pulls when credentials aren’t available.

Tip

If you aren't ready for review, convert to a draft PR.
Click "Convert to draft" or run gh pr ready --undo.
Click "Ready for review" or run gh pr ready to reengage.

Changes:

Introduce registry auth resolution via ~/.docker/config.json / DOCKER_CONFIG, supporting credHelpers, credsStore, and inline auths.
Add a comprehensive unit test suite covering host resolution, config loading, helper execution, and fallback behavior.
Wire registry auth into the image pull path so deployments can authenticate to private registries.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
internal/docker/registry_auth.go	Implements Docker config parsing and credential helper/inline auth resolution for registry pulls.
internal/docker/registry_auth_test.go	Adds tests for registry host parsing, config lookup, helper execution, and graceful fallbacks.
internal/docker/application.go	Passes resolved `RegistryAuth` into `ImagePull` to enable authenticated pulls.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

You can also share your feedback on Copilot code review. Take the survey.

internal/docker/registry_auth.go

+func authFromCredHelper(helper, serverURL string) string {
+	cmd := exec.Command("docker-credential-"+helper, "get")
+	cmd.Stdin = strings.NewReader(serverURL)
+	out, err := cmd.Output()
+	if err != nil {


internal/docker/registry_auth.go

+type dockerAuthEntry struct {
+	Auth string `json:"auth"`
+}


internal/docker/registry_auth.go

+	if entry, ok := authEntryFor(cfg.Auths, host); ok && entry.Auth != "" {
+		return authFromInlineEntry(entry.Auth)
+	}


Copilot AI review requested due to automatic review settings March 19, 2026 10:32

Copilot AI reviewed Mar 19, 2026

View reviewed changes

franzejr added 2 commits March 19, 2026 07:39

Copilot AI review requested due to automatic review settings March 19, 2026 10:46

Copilot AI reviewed Mar 19, 2026

View reviewed changes

franzejr added 2 commits March 19, 2026 07:52

Copilot AI review requested due to automatic review settings March 19, 2026 11:04

Copilot AI reviewed Mar 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Support pulling private images via Docker credentials#18

Support pulling private images via Docker credentials#18
franzejr wants to merge 5 commits intobasecamp:mainfrom
franzejr:add-private-registry-support

franzejr commented Mar 19, 2026 •

edited

Loading

Uh oh!

franzejr commented Mar 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

franzejr Mar 19, 2026

Uh oh!

franzejr Mar 19, 2026

Uh oh!

franzejr Mar 19, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

franzejr Mar 19, 2026

Uh oh!

franzejr Mar 19, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

franzejr commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Plan

Automated

Manual (private image)

Fallback behaviour

Uh oh!

franzejr commented Mar 19, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

franzejr Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

franzejr Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

franzejr Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

franzejr Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

franzejr Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

franzejr commented Mar 19, 2026 •

edited

Loading

franzejr Mar 19, 2026 •

edited

Loading