cloudfoundry · anita-flegg · Sep 26, 2025 · Sep 23, 2025 · Sep 23, 2025 · Sep 23, 2025
diff --git a/deploy-apps/push-docker.html.md.erb b/deploy-apps/push-docker.html.md.erb
@@ -164,6 +164,14 @@ Apps require access to the container registry when starting.
 If you do not update the app with the new credentials, <%= vars.app_runtime_abbr %> fails to start the app.
 When you rotate container credentials, <%= vars.recommended_by %> recommends using a set of two credentials, where the <code>old</code> credentials can be deactivated after all apps are pushed with the <code>new</code> credentials.
 
+### <a id='registry-credentials'></a> Basic Authentication with stored Registry Credentials
+
+Admins, Org Managers, and Space Developers can store Docker registry credentials for reuse among developers using Registry Credentials.
+
+When using Registry Credentials, apps can use the stored credentials instead of requiring credentials on each push.
+
+For more information, see [Using stored Registry Credentials to push Docker apps](registry-credentials.html).
+
 ### <a id='ecr'></a> Amazon Elastic Container Registry (ECR)
 
 <%= vars.app_runtime_abbr %> supports pushing apps from images hosted on Amazon Web Services ECR, which authenticates with temporary password tokens.

diff --git a/deploy-apps/registry-credentials.html.md.erb b/deploy-apps/registry-credentials.html.md.erb
@@ -0,0 +1,140 @@
+---
+title: Using stored Registry Credentials to push Docker apps
+owner: CAPI
+---
+
+Registry Credentials provide a way to share Docker registry credentials across a foundation, organization, or space. Without using Registry Credentials, credentials must be provided for every push when trying to push with an image from a private registry:
+
+```
+CF_DOCKER_PASSWORD=PASSWORD cf push APP-NAME --docker-image REPO/IMAGE:TAG --docker-username USER
+```
+
+By creating Registry Credentials, Admins, Org Managers, and Space Developers can save Docker credentials for reuse among developers.
+
+Registry Credentials can be created at four different levels:
+
+* Foundation
+* Organization
+* Space
+* App
+
+For example, an Org Manager can create a Registry Credential for an Organization, which will be available to all Apps within that Organization:
+
+```
+cf target -o ORG
+CF_DOCKER_PASSWORD=PASSWORD cf create-org-registry-credential REGISTRY-LOCATION --username USER
+```
+
+After the Registry Credential is created, Space Developers can push apps referencing images in the private registry without providing credentials:
+
+```
+cf push APP-NAME --docker-image REGISTRY-LOCATION/REPO/IMAGE:TAG
+```
+
+## <a id='creating'></a> Creating Registry Credentials for a Foundation, Organization, or Space
+
+Registry Credentials can be created for a Foundation, Organization, or Space using the `cf create-foundation-registry-credential`, `cf create-org-registry-credential`, or `cf create-space-registry-credential` commands.
+
+For example, an Admin can create a Registry Credential for the Foundation:
+
+```
+cf create-foundation-registry-credential REGISTRY-LOCATION --username USER
+```
+
+The password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users are prompted for the password.
+
+- **Foundation-scoped Registry Credentials** are available to all Apps on the platform and can only be created or altered by an Admin.
+- **Organization-scoped Registry Credentials** are available to Apps within the Organization and can only be created or altered by an Org Manager or Admin.
+- **Space-scoped Registry Credentials** are available to all Apps within the Space and can be created or altered by a Space Developer or Admin.
+
+The `create-org-registry-credential` and `create-space-registry-credential` commands are context sensitive and create Registry Credentials for the Organization or Space that the user is currently targeting. For example, to create a Space-scoped Registry Credential, the user must target the Space first:
+
+```
+cf target -o ORG -s SPACE
+cf create-space-registry-credential REGISTRY-LOCATION --username USER
+```
+
+`REGISTRY-LOCATION` must include a host name, and may include paths and/or ports; for example, `registry.example.com`, `registry.example.com/path`, `registry.example.com/path/to/repo:5000`. Protocols such as `https://` must not be included.
+
+## <a id='app-registry-credential'></a> Creating Registry Credentials for an app
+
+If an App is pushed with Docker credentials provided, an App-scoped Registry Credential is created automatically for the App, allowing future pushes to omit credentials.
+
+This Registry Credential is only available to the App and cannot be shared with other Apps; it takes precedence over any other Registry Credential for that particular private registry.
+
+Providing new credentials on future pushes updates the App-scoped Registry Credential.
+
+App-scoped Registry Credentials are only created or updated during the 'start' phase of the push. If a push fails during staging (potentially due to incorrect credentials), for example, the App-scoped Registry Credential is not created.
+
+## <a id='using'></a> Using Registry Credentials
+
+When pushing an app, the Registry Credential is selected by the following order of precedence:
+
+1. App-scoped Registry Credential
+1. Space-scoped Registry Credential
+1. Organization-scoped Registry Credential
+1. Foundation-scoped Registry Credential
+
+Among each level, the Registry Location is extracted from the image reference and used to find a possible matching Registry Credentials. More specific matches are preferred.
+
+For example, if an App is pushed with the image reference `registry.example.com/repo/image:tag`, App-scoped Registry Credentials are searched for in the following order:
+
+1. `registry.example.com/repo`
+1. `registry.example.com`
+1. `example.com`
+
+If no App-scoped Registry Credential is found, the same search is performed for Space-scoped Registry Credentials, then Organization-scoped Registry Credentials, and finally, Foundation-scoped Registry Credentials.
+
+If no matching Registry Credential is found, the app push continues as normal, in case the image is publically accessible.
+
+Images references of the form `REPO/IMAGE:TAG` (i.e. with no registry host name) search for Registry Credentials for `docker.io/libary` or `docker.io`.
+
+## <a id='deleting'></a> Deleting Registry Credentials
+
+Registry Credentials can be deleted using the appropriate command:
+
+```
+cf delete-foundation-registry-credential REGISTRY-LOCATION
+cf delete-org-registry-credential REGISTRY-LOCATION
+cf delete-space-registry-credential REGISTRY-LOCATION
+cf delete-app-registry-credential REGISTRY-LOCATION APP-NAME
+```
+
+Deleting a Registry Credential causes any apps that were pushed with that Registry Credential to fail to stage and start in the future, unless other Registry Credentials are made available to them.
+
+## <a id='updating'></a> Updating Registry Credentials
+
+Registry Credentials can be updated using the appropriate command:
+
+```
+cf update-foundation-registry-credential REGISTRY-LOCATION --username USER
+cf update-org-registry-credential REGISTRY-LOCATION --username USER
+cf update-space-registry-credential REGISTRY-LOCATION --username USER
+```
+
+App-scoped Registry Credentials can be updated by pushing the app with new credentials:
+
+```
+cf push APP-NAME --docker-image REGISTRY-LOCATION/REPO/IMAGE:TAG --docker-username USER
+```
+
+Like the creation commands, the password for the Registry Credential can be provided using the `CF_DOCKER_PASSWORD` environment variable. If the environment variable is not set, users are prompted for the password.
+
+Only username or password may be updated; the registry location cannot be changed.
+
+## <a id='listing'></a> Listing Registry Credentials
+
+All Registry Credentials available to the currently targeted Organization and Space can be listed with the `cf registry-credentials` command:
+
+```
+$ cf registry-credentials
+Showing registry credentials available to org 'myorg' and space 'myspace'...
+location                       scope          username            app name
+docker.io/library              app            myuser              myapp
+registry.example.com           space          spaceuser
+registry.example.com/repo      organization   orguser
+docker.io/libary               foundation     docker-user
+registry.example.com/repo      foundation     private-repo-user
+```
+
+If no space or organization is targeted, only Registry Credentials available to the foundation are listed.
diff --git a/index.html.md.erb b/index.html.md.erb
@@ -29,6 +29,7 @@ If you do these things, you are a <%= vars.app_runtime_abbr %> **developer**, a
   * [Deploying with app manifests](deploy-apps/manifest.html)
   * [App manifest attribute reference](deploy-apps/manifest-attributes.html)
   * [Deploying your app with Docker](deploy-apps/push-docker.html)
+  * [Using shared Registry Credentials for Docker apps](deploy-apps/registry-credentials.html)
   * [Deploying your large apps](deploy-apps/large-app-deploy.html)
   * [Starting, restarting, and restaging apps](deploy-apps/start-restart-restage.html)
   * [Pushing an app with multiple processes](multiple-processes.html)