# pull: true silently falls back to cached image when registry authentication fails

[Terracast-cmd]

pull: true silently falls back to cached image when registry authentication fails

Component

agent

Describe the bug

When using pull: true on a step with a private registry image, if the agent doesn't have valid credentials configured for that repository but the image exists in the local Docker cache (pulled previously by another repository's pipeline that had valid credentials), the step succeeds silently instead of failing with an authentication error.

This is a security concern because:

1. Repository A with valid registry credentials pulls registry.example.com/image:latest → image is now cached on the agent
2. Repository B without any registry credentials uses the same image with pull: true
3. Expected: Pipeline fails with authentication error
4. Actual: Pipeline succeeds, using the cached image

The pull: true option should enforce authentication with the registry, not silently fall back to cached images when auth fails.

Steps to reproduce

1. Set up a private container registry (e.g., Harbor)
2. Configure a Woodpecker agent with Docker backend
3. On Repository A: Configure registry credentials and run a pipeline that uses an image from the private registry → image gets cached on the agent
4. On Repository B: Do NOT configure any registry credentials
5. Create a pipeline in Repository B using the same private image with pull: true:

steps:
  - name: test
    image: your-private-registry.com/some/image:latest
    pull: true
    commands:
      - echo "This should not work without credentials"

6. Run the pipeline

Expected behavior: Pipeline fails with authorization failed: no basic auth credentials

Actual behavior: Pipeline succeeds, silently using the cached image

Additional context

I initially noticed that repositories without registry credentials could use private images if they were already cached on the agent (pulled by other repositories with valid credentials). I tried using pull: true as a workaround to force credential validation on every pull, but discovered that it silently falls back to the cached image when authentication fails.

This behavior breaks the isolation model between repositories. The pull: true option is documented as:

By default, Woodpecker does not automatically upgrade container images and only pulls them when they are not already present. To always pull the latest image when updates are available, use the pull option.

The current behavior means:

• pull: true does not guarantee that valid credentials exist for the registry
• Repositories can "inherit" access to private images through the shared Docker cache on the agent
• Users have a false sense of security when configuring per-repository registry credentials

Suggested fix

When pull: true is set, Woodpecker should fail the step if the pull operation fails for any reason (including authentication), rather than falling back to a cached image.

Alternatively, if fallback is intentional, it should be:

1. Clearly documented
2. Optionally disabled via a flag like pull: always-auth or pull: strict

Environment

• Woodpecker server: v3 (woodpeckerci/woodpecker-server:v3)
• Woodpecker agent: v3 (woodpeckerci/woodpecker-agent:v3)
• Agent backend: Docker
• Docker version: 28.5.1
• Registry: Harbor (private project)
• Agent OS: macOS (Docker Desktop)

Note

I've only been using Woodpecker for a few months, so I may have missed something in my configuration. If this is expected behavior or a misconfiguration on my part, I'd appreciate any guidance. However, after checking the documentation and my setup thoroughly, I couldn't find any explanation for this behavior.

Related

This is related to the broader question of image cache isolation between repositories on shared agents, but this specific issue is about pull: true not behaving as expected.

[qwerty287]

There is a separate error handling for this case in the code already: https://github.com/woodpecker-ci/woodpecker/blob/main/pipeline/backend/docker/docker.go#L200-L204

Seems that it does not work then though…