Before comparing the two visibility modes, it helps to be precise about what a repository actually is, and what “visibility” specifically controls.

What a Repository Is

A repository is a named collection of related container images living inside a registry, typically representing different versions of the same piece of software over time. For example, the nginx repository on Docker Hub contains every published version of the Nginx web server image, distinguished from one another by their tags. A registry can host thousands of separate repositories, each independently configured with its own visibility, access rules, and permissions.

What Visibility Actually Controls

Visibility determines who is allowed to pull images from a repository, and, separately, who is allowed to push new images into it. A public repository allows anyone, including someone with no account on the registry at all in many cases, to pull its images freely. A private repository requires the puller to be authenticated as an account, team, or service that has been explicitly granted access — everyone else receives a clear denial, as though the repository simply didn’t exist for them.

Push Access Is a Separate Question From Pull Access

It’s important to separate two distinct permissions that are often conflated: who can pull (download and use) an image, and who can push (upload and publish a new version of) an image. Even a fully public repository, readable by anyone, almost always restricts push access to a specific, trusted set of accounts — otherwise anyone in the world could silently overwrite a popular public image with something malicious, which would be a catastrophic design flaw. Visibility mainly governs the pull side; push access is governed by a separate, always-restricted permission model regardless of whether the repository is public or private.

Understanding how visibility is enforced technically requires a quick look at how a registry structures accounts, organizations, repositories, and permissions.

The Account and Organization Layer

Most registries organize repositories under either an individual user account or a shared organization account, similar to how a personal GitHub account differs from a company’s shared GitHub organization. A repository’s full name typically embeds this owner, such as someuser/myapp or somecompany/internal-service, making clear at a glance which account or organization is responsible for it.

flowchart TD
    A["Registry Account /
Organization"] --> B["Repository:
myapp"]
    B --> C{Visibility Setting}
    C -->|Public| D["Anyone can PULL
(no authentication needed)"]
    C -->|Private| E["Only explicitly granted
accounts can PULL"]
    B --> F["Push Permission List
(always restricted, both cases)"]
    F --> G["Authorized maintainers only
can PUSH new images"]
        

Authentication and Authorization Tokens

When a client attempts to pull from a private repository, the registry requires it to first authenticate, typically via a username and password or a scoped access token, and then checks whether that authenticated identity has been explicitly granted permission to read that specific repository. Only if both checks pass does the registry serve the requested manifest and layers. For a public repository, this check is effectively skipped for the pull operation — the registry serves the content to any request, authenticated or not.

Team and Role-Based Access Control

Private repositories in most professional registry offerings support fine-grained, role-based permissions beyond a simple binary in-or-out list: some team members might be granted read-only pull access, while others receive full read-write access allowing them to also push new versions, and administrators can further scope this by individual repository rather than granting blanket access across an entire organization’s full catalog of private images.

Tracing exactly what happens inside the registry when a pull request arrives clarifies why visibility works the way it does, and where the enforcement actually happens.

Step One: The Pull Request Arrives

When a client requests a manifest or layer from the registry’s API, the very first thing the registry does is look up which repository is being requested and check its stored visibility setting. This lookup happens before any content is served, acting as the first gate in the entire process.

Step Two: The Public Path — Immediate Service

If the repository is marked public, the registry serves the requested manifest or layer immediately, without requiring or even checking for any authentication credentials on the request at all. This is precisely why running a pull command against a well-known public image, like an official base image, works instantly even on a machine that has never logged into that registry before.

Step Three: The Private Path — Credential Verification

If the repository is marked private, the registry instead responds with an authentication challenge if no credentials were provided, or checks the provided credentials against its access control records if they were. Only an identity explicitly listed with pull permission for that specific repository receives the actual content; every other identity, including a perfectly valid, logged-in account that simply wasn’t granted access to that particular repository, receives a denial.

sequenceDiagram
    participant C as Client
    participant R as Registry
    participant ACL as Access Control Records
    C->>R: Request manifest for repo "myapp"
    R->>R: Look up repo visibility setting
    alt Repository is Public
        R-->>C: Serve manifest immediately
    else Repository is Private
        R->>C: Request authentication credentials
        C->>R: Provide credentials/token
        R->>ACL: Check if identity has pull permission
        alt Permission Granted
            ACL-->>R: Access approved
            R-->>C: Serve manifest
        else Permission Denied
            ACL-->>R: Access denied
            R-->>C: Return access denied error
        end
    end
        

Push Verification Happens the Same Way, Every Time

Regardless of a repository’s visibility, any attempt to push a new image always triggers the same authentication and authorization check described for private pulls — the registry always verifies the pushing identity has explicit write permission for that repository before accepting the upload. This uniform enforcement on the push side is what keeps public repositories safe from unauthorized tampering despite being freely readable.

Local Caching Doesn’t Bypass Registry-Side Rules

It’s worth noting that once an authorized pull successfully retrieves an image, that image lives on the local machine independently of the registry’s ongoing access rules. If a private repository’s permissions are later revoked for a particular account, images that account already pulled and stored locally remain usable locally; only future pull attempts against the registry are affected by the permission change, not content already downloaded.

Following an image through its full lifecycle — from creation to eventual retirement — shows how visibility decisions can, and sometimes need to, evolve over time.

Why Visibility Changes Deserve Extra Caution

Switching a repository from private to public is a one-directional trust decision in an important sense: once an image has been pulled by even a single outside party while public, there is no way to retroactively “unshare” the copies that party already downloaded. Conversely, switching a previously public repository to private doesn’t retroactively revoke access for anyone who already has a local copy of images pulled during the time it was public — a detail teams sometimes overlook when trying to correct an earlier visibility mistake.

CI/CD Systems as a Special Kind of Consumer

Automated build and deployment pipelines are frequently granted their own dedicated service account credentials scoped specifically to pull from, and sometimes push to, particular private repositories, separate from any individual human team member’s personal credentials. This keeps automated systems working reliably even as individual employees join or leave a team, and allows access for automation to be reviewed and revoked independently of personal account permissions.

Neither visibility mode is inherently correct — the right choice depends entirely on what the image contains and who genuinely needs to use it.

The Core Trade-off: Reach Versus Control

Choosing public trades away control over who can see and use your content in exchange for maximum reach, discoverability, and ease of adoption — exactly what an open-source project or a general-purpose base image needs. Choosing private trades away that broad reach in exchange for tight control over exactly who can access potentially sensitive or proprietary content — exactly what an internal company application needs. Neither trade-off is free; the right choice depends entirely on what the image actually contains and who legitimately needs it.

Cost Considerations

Many registries structure their pricing around private repository storage and bandwidth, since public repositories generally serve the platform’s own interest in hosting a rich, freely accessible ecosystem of software. Organizations with many private repositories, especially ones with large images or high pull volume from automated systems, often need to actively plan around these costs as part of their overall infrastructure budget, in a way that public repository usage rarely requires.

Collaboration Overhead as a Hidden Cost

Beyond direct storage and bandwidth pricing, private repositories carry a quieter, often underestimated cost: someone has to actually manage the access list. Every new team member who needs pull access, every contractor whose engagement ends, and every service account that needs its credentials rotated represents ongoing administrative work that a fully public repository simply never requires, since there is no list to maintain in the first place. This overhead is usually worth paying for genuinely sensitive software, but it is a real, recurring cost that should factor into the decision rather than being treated as free just because it doesn’t appear on an invoice.

Because visibility directly controls who can see an image’s contents, it sits close to the center of any organization’s container security posture.

What a Public Image Can Accidentally Reveal

Every layer of a container image is, in principle, inspectable by anyone who can pull it — including a public one. This means source code accidentally copied into a public image, hardcoded credentials left in a configuration file, or internal hostnames and system architecture details embedded during a careless build can all become visible to literally anyone in the world the moment that image is pushed to a public repository, even if the visibility choice itself was otherwise entirely reasonable for that project.

Why Private Doesn’t Mean “Automatically Safe to Be Careless”

A private repository significantly reduces exposure, but it does not eliminate the need for careful practices, because every account granted access to that private repository can still see everything inside it. A private repository with dozens of team members and several third-party service accounts granted broad access is not meaningfully different, from a “how many people could see this” standpoint, than a smaller, carefully curated public repository — the label “private” describes a mechanism, not a guarantee of a small or trustworthy audience.

Scanning Public and Private Images Alike

Vulnerability scanning matters for both visibility types, though the calculus differs slightly: a popular public image is scanned constantly by many independent parties, meaning issues are often caught and reported quickly by the broader community, while a private image usually depends entirely on the owning organization’s own internal scanning practices, since no outside party can even see it well enough to report a problem.

Because visibility is a security-relevant setting, not just an access convenience, it deserves active, ongoing monitoring rather than a one-time decision made and forgotten.

Auditing Repository Visibility Settings

Organizations with many repositories across many teams benefit enormously from a regular, automated audit that lists every repository’s current visibility setting, flagging any private repository that was unexpectedly switched to public, or any repository containing sensitive-sounding names that is currently public and possibly shouldn’t be. Catching a visibility misconfiguration through a scheduled audit is far less costly than discovering it after a security incident.

Logging Who Pulled What, When

For private repositories especially, maintaining a log of exactly which authenticated identity pulled which image and when provides a valuable audit trail, both for routine compliance reporting and for reconstructing exactly what happened during a security investigation, such as determining whether a since-revoked credential was used to access sensitive content before its access was removed.

A Real Pattern: Automated Secret Scanning Before Push

Many organizations integrate an automated scanning step directly into their build pipeline that inspects an image’s layers for patterns resembling credentials, API keys, or private certificates before allowing the push to proceed at all, regardless of the target repository’s visibility. This shifts the safety check earlier in the process, catching a mistake before it ever reaches a registry rather than relying entirely on visibility settings as the only safeguard.

Alerting on Anonymous Pull Spikes for Public Repositories

Even for intentionally public repositories, monitoring is still worthwhile: a sudden, unexplained spike in pull volume can indicate the image has been referenced in a widely shared tutorial or picked up by a popular open-source project, which is useful, actionable context for a maintainer deciding where to invest documentation effort — or, less happily, it can indicate the image is being pulled as part of an automated scanning sweep looking for known vulnerabilities across the entire public registry, which is worth knowing about even though the repository’s openness was always the intended design.

Years of collective experience across organizations of every size have produced clear, well-tested conventions for structuring public and private repositories well.

Pattern: Default to Private, Promote to Public Deliberately

The safest organizational default is creating every new repository as private, and only switching a specific repository to public after a deliberate review confirming the team genuinely intends to share that software broadly and has verified it contains nothing sensitive. This reverses the risk of the far more dangerous default, where a forgotten or accidentally public repository sits exposed simply because nobody explicitly chose to make it private.

Pattern: Separating Public Base Images From Private Application Images

A common, effective structure keeps generic, reusable base images — the kind that provide genuine value to a wider community and contain nothing proprietary — in public repositories, while keeping the actual proprietary application images that are built on top of those bases in private repositories. This captures the reach benefit of public sharing for the genuinely shareable parts, while keeping the sensitive, business-specific parts properly protected.

Pattern: Scoped Service Accounts Instead of Shared Personal Credentials

Rather than sharing one team member’s personal login across an entire CI/CD pipeline, mature setups create dedicated, narrowly scoped service accounts with access limited to exactly the specific private repositories that pipeline actually needs, making it possible to revoke or rotate that access independently of any individual person’s own credentials.

Anti-pattern: Treating “Private” as a Substitute for Actual Access Control Review

Some teams treat setting a repository to private as the end of their security thinking on the matter, without ever actually reviewing or tightening the specific list of accounts granted access to it. A private repository accessible to a hundred loosely tracked accounts offers only marginally better protection than a public one, undermining much of the actual benefit the private setting was meant to provide.

A practical, consolidated checklist for handling repository visibility responsibly in real organizations.

Common Mistake: Assuming a Repository’s Name Being Obscure Provides Real Protection

Some teams leave a repository public but give it a deliberately obscure or hard-to-guess name, assuming that obscurity alone provides meaningful protection. Public repositories are frequently discoverable through search functionality, indexing, or simple guessing, so an obscure name is not a substitute for the actual access control that a private setting provides.

Common Mistake: Forgetting That Forked or Mirrored Copies May Already Exist

Once an image has been public for any length of time, automated systems, archival services, or individual users may have already pulled and stored their own independent copies. Switching visibility back to private after the fact does nothing to affect these already-existing external copies, which is an important reality to factor into any incident response plan involving previously public content.

Common Mistake: Treating Every Private Repository as Equally Sensitive

Not every private repository carries the same level of risk if exposed, and treating them all identically can lead to either wasted effort protecting genuinely low-stakes internal tools with the same rigor as a repository containing real production secrets, or worse, applying insufficient scrutiny to a highly sensitive repository simply because it happens to sit next to less sensitive ones in the same organization’s account. Classifying private repositories by their actual sensitivity, and matching access review frequency and scanning rigor to that classification, produces a far more efficient and genuinely protective security program than a one-size-fits-all approach applied uniformly across everything marked private.

The public-versus-private decision plays out constantly across the industry, shaping how companies structure their entire container strategy.

Example: Official Open-Source Images

Widely used official images such as Nginx, Postgres, and Python live in public repositories specifically because their entire value proposition depends on broad, frictionless reach — a web server or database engine used by millions of projects worldwide needs to be pullable by anyone, anywhere, without any account setup or approval process standing in the way.

Example: Enterprise Internal Application Images

A typical financial services or healthcare company keeps essentially all of its internal application images in private repositories, often further segmented by team or business unit, reflecting both the proprietary nature of internal business logic and strict regulatory requirements around controlling exactly who can access systems that may process sensitive customer data.

Example: Open-Source Projects With a Mixed Strategy

Some companies that build commercial products on top of open-source foundations maintain a public repository for their freely available, community edition image, while keeping a separate private repository for their proprietary, paid enterprise edition image, cleanly separating what’s meant for broad community adoption from what’s meant only for paying customers with explicitly granted access.

Example: A Well-Known Accidental Exposure Pattern

Security researchers have repeatedly documented cases across the industry where a private-sounding internal tool was mistakenly pushed to a public repository, sometimes due to a misconfigured default in an automated pipeline, exposing internal source code or configuration to anyone who happened to search for it before the mistake was caught. These well-documented, recurring incidents are exactly why “default to private” and “automated secret scanning” have become such widely recommended practices across the industry.

Public versus private is a simple binary switch on the surface, but it sits at the intersection of security, cost, collaboration, and compliance, and deserves a deliberate, ongoing decision rather than a one-time, forgotten setting.