Repository missing from Proxy Cache project after successful image pull

[blankirigaya]

Expected behavior vs actual behavior:

Expected Behavior

When an image is pulled through a Proxy Cache project, Harbor should create and display the corresponding repository entry for that project, regardless of whether the image already exists in the local Docker cache.

Actual Behavior

In some cases, the image pull succeeds, but the repository entry is not created or displayed in the project. As a result, the repository is missing from both the Harbor UI and the /api/v2.0/projects/<project>/repositories API response.

---

Steps to reproduce the problem:

1. Create two Proxy Cache projects (e.g. proj1 and proj2) backed by Docker Hub.

2. Pull an image through the first project:

for example:-
docker pull localhost:8080/proj1/library/traefik:latest

3. Verify that the repository appears in proj1.

4. Pull the same image through the second project:

   docker pull localhost:8080/proj2/library/traefik:latest

5. Check the repositories for proj2:

   curl -u admin:
   "http://localhost:8080/api/v2.0/projects/proj2/repositories"

6. Observe that the pull succeeds, but the repository entry may not be created or displayed in Harbor for proj2.

Versions:

• Harbor version: 2.14
• Docker Engine version: 23.9.1
• Docker Compose version: 2.40.3

Additional context:

• Tested on Harbor built from the current main branch.

[SurbhiAgarwal1]

Hi @Vad1mo ,

I believe the issue is caused by the repository creation logic being tied to artifact synchronization rather than project-repository association.

Currently, when an image is pulled through a Proxy Cache project, Harbor correctly creates the repository entry if the artifact is fetched from the remote registry. However, if the same artifact already exists locally (because it was previously pulled through another Proxy Cache project), Harbor appears to serve the cached artifact directly and skips creating the repository record for the new project.

Proposed Fix

Decouple repository creation from artifact download/cache-hit logic.

When handling a proxy-cache pull request:

1. Resolve the target Proxy Cache project.

2. Check whether the repository exists within that project.

3. If the repository does not exist:

   • Create the repository record.
   • Associate it with the current project.

4. Proceed with artifact resolution:

   • Serve the local artifact if it already exists.
   • Otherwise fetch it from the upstream registry.

This ensures repository metadata is always created regardless of whether the pull results in a remote fetch or a local cache hit.

Suggested Implementation Areas

• src/controller/proxy
• Proxy Cache pull workflow
• Repository creation/association services
• Artifact synchronization logic
• Cache-hit handling path

Test Coverage

Add integration tests covering:

Scenario 1: Cross-Project Cache Reuse

• Pull image through Proxy Cache Project A.
• Pull the same image through Proxy Cache Project B.
• Verify repository entries exist in both projects.

Scenario 2: Existing Local Artifact

• Seed Harbor with an artifact.
• Pull it through a new Proxy Cache project.
• Verify repository creation occurs even when no remote fetch happens.

Expected Result

• Successful pulls always create the expected repository entry.
• Repository visibility is consistent between UI and API.
• Multiple Proxy Cache projects can reference the same cached artifact without losing repository metadata.
• Cache hits and remote downloads follow identical repository registration behavior.

[Vad1mo]

related to #19609

[MinerYang]

It is a expected behavior if you are using docker client.
Docker client pull skip send the HEAD tag request with a local cache. Harbor never received a request for the latest tag underproj2 , the repository entry would skipped to be created.

[stonezdj]

see faq: https://github.com/goharbor/harbor/wiki/Why-it-can't-create-tag-after-pulling-image-from-proxy-cache%3F