Request for comments (RFC) - Permission system for docker image registry

[#1]

Hi everyone - This RFC is to gather ideas/feedback on our planned implementation for a Docker Image Registry feature for Bitbucket Cloud, a new feature coming later this year. This feature aims to enable users to publish, manage, and consume Docker images directly within Bitbucket Cloud.

Although initially limited just to Docker/OCI images, this functionality will eventually be expanded to support common library/package registries as well.

We are particularly interested in your thoughts on the permissions/access model associated with this feature. Your insights will be invaluable in helping us refine this functionality to better align with your workflows

Motivation

Currently, Bitbucket users rely on external package management solutions for Docker images and other types of packages which introduces several challenges:

• Developers must switch between Bitbucket and external tools, reducing productivity

• Permissions must be managed separately in external systems, leading to inconsistencies and potential security risks

Summary

The Docker Image Registry will integrate directly into Bitbucket Cloud at the workspace level, providing a centralized hub for managing Docker images. While the image registry exists at the workspace level (one namespace per workspace), images will be linked to specific repositories and inherit the repositories permissions by default, with options for administrators to customize access to individual images as needed.

Example Usage

The registry will operate at the workspace level, with images linked to individual repositories. Permissions will align with existing repository roles (Admin, Write, Read), though image admins can override these settings where necessary. Below are the key use cases:

1. Creating a New Image

   • Role: Image Admin (Repository admin permission)

   • Description: Responsible for publishing a new Docker image to the registry for the first time - or creating the required record in Bitbucket Cloud to map an image name to a repository, so another user (with write permissions) can push the first version of the image.

2. Pushing a New Version of an Existing Image

   • Role: Image Publisher (Repository write permission)

   • Description: Can push updates or new versions of an existing image. Can push the initial version of an image if a record has already been created in Bitbucket to map the image name to a repository where the user has write permissions.

3. Consuming an Existing Image

   • Role: Image Consumer (Repository read permission)

   • Description: Can pull and use already published images from the registry.

   • Note: It will be possible for Image Admins to also mark individual images as “Public”, making them consumable to any user in the workspace without granting users read permissions on the repository the image is linked to.

4. Editing Image Settings

   • Role: Image Admin (Repository admin permission)

   • Description: Can adjust image permissions, such as making an image accessible to everyone in the workspace (read-only).

Core Flow 

Rationale

After extensive research of alternative/competitor solutions, we settled on this proposed model for a number of reasons.

• We want to be able to utilise the existing functionality we have in the repo/project hierarchy to infer or create ergonomic permissions structures, something only possible if Images are explicitly linked to a particular repository.

  • For example, we may want to allow customers to grant certain Pipelines deployment environments implicit write permissions to images linked to the repo that environment is part of, allowing Pipelines to publish image updates without requiring any kind of tokens to be managed or passed to Pipelines by a user.

  • We also want to make sure customers can utilise their existing user/group permissions structures to manage access to images (especially if those groups are managed via an external IDP), rather than having to create an entire parallel permissions structure just for images.

• Some competitors allow customers to create multiple registries, either at the “workspace” (equivalent) level, OR at the “repository” (equivalent) level, or both. From our testing and personal experience, this can be extremely cumbersome to manage and administer, and creates extremely complex and problematic security/permissions constructs.

• Some solutions allow any user to push the initial version of an image to the global registry, before then associating it with a repository later. From our testing and personal experience, this can cause issues for registry management and also complexities in permissions models. It results in one of the following undesired scenarios:

  • Any user can push an image to the global registry, but then a Workspace administrator is required to come along and associate that new image to a repository in order for permissions to be applied.

    • This places extensive effort on the Workspace admin.

    • It also creates a large risk of “orphaned” images clogging up the registry.

  • Any user can push an an image to the global registry, and that same user takes “ownership” of that image, and can then associate it with a repository later.

    • This doubles the complexity of the overall permissions model as images must now support two parallel permissions schemes. One based on individual user ownership, and the other based on the existing repository based permissions model.

    • It also introduces questions/complexities around the fact that users would only be able to link images to repos they have admin permission over - meaning a repo admin must still be involved in the process anyway.

    • It introduces the same risk of “orphaned” images clogging up the registry.

Key Questions for Feedback

We’d love your thoughts on the proposed permissions model:

• What are your views on the baseline assumption of attaching images stored in Bitbucket Cloud to repositories existing within the system?

  • Does this approach align with your current workflows?

  • Are there existing structures/capabilities tied to the repository that you would like to see integrated with an image registry?

  • Are there situations you would not want this to be the baseline structure?

• What are your views on the baseline assumption of inheriting permissions from the existing Bitbucket permissions structure?

  • Does this approach align with your current workflows?

  • Are there situations you would not want this to be the baseline structure?

• Are there any specific use cases where these structures would not work for your workflows or use-cases.

Your feedback will be crucial in refining this feature to ensure it aligns with customer requirements. Let us know what you think in the comments section below.

[Ari Hannula]

Our pipelines are using a very simple Docker image that is currently in Dockerhub. It rarely needs to be changed/updated. It would be great if we could get rid of using Dockerhub. I see you have already done a proper analysis. The suggested design would be fine for us. Go for it!

[Dejan Subotic]

We are building and pushing many docker images (and other artifacts) daily and we use external artifactory for this. External artifactories charge per storage and per total data transfer. Workflow seems reasonable but big question here would be the cost of the whole thing. It would be great if we could get some inputs regarding the projected costs. 

Many thanks! 

[Jeremy]

What are your views on the baseline assumption of attaching images stored in Bitbucket Cloud to repositories existing within the system?

- This would be great. Currently storing public image on Docker Hub for Bitbucket Pipeline pipe and storing it non-public here would also be nice.

- Registry should be able to store multi-architecture (amd64/arm64) images and should be able to build it in Bitbucket Cloud runner (currently not possible, because cloud runner does not allow privileged containers)

- Should be able to have a option to add cron-job with regex for cleaning up old images in the registry (like Azure container-registry-auto-purge)

What are your views on the baseline assumption of inheriting permissions from the existing Bitbucket permissions structure?

- Would like to see a option that creating/updating a image is only allowed through Bitbucket Pipelines. 

[Suresh Kamble]

TLDR; we are looking for a platform-agnostic system that provides a transparent layer over existing registries, allowing for centralised management and permission control within Bitbucket, without requiring a full migration.

We have a complex environment with multiple projects and repositories generating OCI images.

Specifically, we'd greatly benefit from a transparent proxy or mirror configuration that allows us to connect to an existing, external registry.

This would provide several advantages:

Reduced admin overhead by

Hiding and decoupling the primary source of the registry and its authentication behind a configurable remote registry would significantly reduce the administrative effort required for each workspace, project, and repository.

If an admin configures a remote registry at a higher level in the hierarchy (e.g., workspace or project), those images should be available by default. High-level permissions could then be abstracted for repository or project owners and contributors.

External / Existing registry connection would also help us achieve greater freedom from vendor lock-in, as we could easily switch or connect to different registries without impacting individual repositories.

Migrating away from our existing image registry is not a viable option for our team at this time. Proxy/mirror configuration would allow us to leverage Bitbucket's permission system while maintaining compatibility with our current infrastructure.

I believe that this approach would greatly enhance the flexibility and usability of above Registry, particularly for orgs with complex environments and existing registry dependencies.

[Faye Salwin]

This is likely to simplify cross-step image propagation, a focus on fast operations would be appreciated.  Will pipe containers come from Bitbucket by default?  Is it going to work easily for self-hosted runners?

[A Sai Shree Anjan]

This is great! A more robust permission system for the Docker image registry is definitely a good step forward.

Additionally, it would be great if Bitbucket could provide Shared macOS runners to support iOS builds. This is a much-needed feature for teams working on iOS apps and would make Bitbucket Pipelines even more complete for mobile development workflows.

Thanks for the continuous improvements!

[Kyle Hancock]

In order to use this we would need to have support for AWS ECR as that is where we store our registries. We currently have to use custom images and a combination of custom docker based and self hosted Linux based runners to build our software. The self hosted Linux runner is only used because caching is so broken in Docker based bitbucket runners. I'd implore you to devise an actual solution (not disabling build-x, or requiring docker-build 1.x - those are hacky work arounds) before adding additional these features.  

[Hamreet Kaur]

Thank you all for your feedback! We’ll be reviewing all the input and will share an update soon. In the meantime, please keep sharing your thoughts—we’ll continue monitoring this to shape our next steps and keep you posted.

[Casey Dement]

I think your permissions scheme aligns very well with a CI/CD SDLC.  Since permissions to automatically deploy to a particular environment are normally associated with the ability to push changes to a repository, associating the ability to store the image that will be deployed with that same set of rights seems a very natural and straightforward solution.

[Jerry tomson]

In order to use this we would need to have support for AWS ECR as that is where we store our registries. We currently have to use custom images and a combination of custom docker based and self hosted Linux based runners to build our software. The self hosted Linux runner is only used because caching is so broken in Docker based bitbucket runners. I'd implore you to devise an actual solution (not disabling build-x, or requiring docker-build 1.x - those are hacky work arounds) before adding additional these features.