Oracle Cloud Infrastructure Documentation

Creating a Repository

Find out how to create a repository in Container Registry.

After you create a standard repository, you can push an image to it using the Docker CLI (see Pushing Images Using the Docker CLI). Any images that you subsequently push to the registry that include the same repository name are grouped into that repository.

When the top-level capability is disabled, a repository name can include slash characters (/). For example, project01/acme-web-app and project01/my-test-app are valid names for separate repositories.

When the top-level capability is enabled, the repository name must contain a single path segment and cannot include slash characters (/). For example, app is a valid repository name, but app/backend is not. After creating repository app, images can be stored at its root path or child paths, such as app:v1 and app/backend:v1. Both belong to repository app.

For more information and examples, see repository name.

When you create a repository, you choose the repository type:

  • Standard: Supports image pushes and pulls and stores images in the selected region.

  • Pull-through cache: A private repository that retrieves requested images from a configured upstream Container Registry registry in the same OCI realm and caches them in the selected region. Clients can pull images from the repository but cannot push images to it.

You can enable the top-level capability when creating either repository type. After the repository has been created, you cannot change its repository type or the top-level capability setting.

Creating a repository before pushing an image is the usual workflow, but it's not always necessary. If you're not authorized to manage repositories in the tenancy's root compartment, you must always push an image to an existing repository. However, if you are authorized to push images to the tenancy's root compartment and you intend to do so, an existing repository is not necessary.

When you push an image, you normally use a command in the format docker push <registry-domain>/<tenancy-namespace>/<repo-name>:<version>. If you select the Create repository on first push in root compartment option and push an image to a path that does not belong to an existing repository, a new private standard repository with the top-level capability disabled is created automatically in the tenancy's root compartment.

For example, if you enter the command docker push ocir.us-ashburn-1.oci.oraclecloud.com/ansh81vru1zp/project02/acme-web-app:7.5.2 and the project02/acme-web-app repository doesn't exist, a private repository called project02/acme-web-app is created automatically in the root compartment.

If the image path belongs to an existing standard repository with the top-level capability enabled, the push adds the image to that repository without creating a separate repository. For example, if standard repository app has the top-level capability enabled, pushing app/backend:v1 adds the image at child path backend in repository app. It does not create a repository named app/backend.

You must belong to the tenancy's Administrators group or have been granted the REPOSITORY_MANAGE permission on the tenancy to automatically create the private repository in the tenancy's root compartment. See Policies to Control Repository Access.

    1. On the Container Registry list page, select Create repository. If you need help finding the list page, see Listing Repositories.
    2. Enter the following information:

      • Create in compartment: The compartment in which to create the repository. You can select any compartment that you have permission to work in.

      • Repository type: Select one of the following repository types:

        • Standard repository: Creates a read-write repository that operates in the current OCI region.

        • Pull-through cache repository: Creates a private repository that retrieves requested images from a configured upstream Container Registry registry in the same OCI realm and caches them in the current OCI region. Clients can pull images from the repository but cannot push images to it.

      • If you selected Pull-through cache repository, specify the following information:

        • Upstream URL: The URL identifying the upstream registry endpoint, upstream tenancy namespace, and repository path or path prefix. The upstream registry must be in a different OCI region within the same OCI realm as the pull-through cache repository. You can specify the URL with or without the https:// scheme.

          • When the top-level capability is disabled, the URL identifies one exact upstream image path.

          • When the top-level capability is enabled, the URL identifies an upstream path prefix. Container Registry appends the requested child path to that prefix to locate the upstream image.

          The following examples use a pull-through cache repository named cache. Local image references omit the registry domain and tenancy namespace for readability.

          Container Registry upstream examples

          Top-level capability disabled/enabled Details
          Top-level capability disabled

          Upstream URL: https://phx.ocir.io/<source-namespace>/team/backend

          Local image reference: cache:v1

          Upstream image reference: phx.ocir.io/<source-namespace>/team/backend:v1
          Top-level capability enabled

          Upstream URL: https://phx.ocir.io/<source-namespace>/team

          Local image reference: cache/backend:v1

          Upstream image reference: phx.ocir.io/<source-namespace>/team/backend:v1

          When the top-level capability is enabled, a namespace-only prefix such as https://phx.ocir.io/<source-namespace> can also be used for child-path pulls. For example, cache/team/backend:v1 maps to phx.ocir.io/<source-namespace>/team/backend:v1. With this configuration, a root reference such as cache:v1 cannot be resolved because it does not identify an upstream image path.

          The upstream repositories do not need to have the top-level capability enabled.

        • Upstream username: The username that Container Registry uses to authenticate to the upstream registry. This user must have permission to pull images from the configured upstream path.

          Use the format <tenancy-namespace>/<username>. For example, ansh81vru1zp/jdoe@acme.com.

          If the upstream user's tenancy is federated with an identity provider supported for Container Registry authentication, use the format <tenancy-namespace>/<domain-name>/<username>, using the domain name shown for that user in the Console. For example, if the tenancy is federated with Oracle Identity Cloud Service and the domain name is oracleidentitycloudservice, enter ansh81vru1zp/oracleidentitycloudservice/jdoe@acme.com.

          Here, <tenancy-namespace> is the Object storage namespace of the upstream user's tenancy, shown on its Tenancy General Information page. For federated users, <domain-name>/<username> is displayed in the Console's Profile menu. See Pushing Images Using the Docker CLI.

        • Upstream secret ID: The OCID of a secret in the customer's OCI Vault containing the upstream user's authentication credential, in the format ocid1.vaultsecret.<realm>.<region>.<unique-id>.

      • Access: For a standard repository, specify whether the repository is public or private. You can only make the repository public if you belong to the tenancy's Administrators group or have been granted the REPOSITORY_MANAGE permission. A pull-through cache repository is always private. Note these points:

        • If you make a standard repository public, any user with internet access and knowledge of the appropriate URL can pull images from the repository.

        • If you make a repository private, you (along with users belonging to the tenancy's Administrators group) can perform operations on the repository for which you are authorized. Pull-through cache repositories do not support client push operations.

      • Enable top-level repository structure: Enable this option to let the repository own its root image path and child paths beneath its name. The option is available for both repository types. When enabled, the repository name must contain a single path segment without /. You cannot change the setting after creation.

      • Repository name: A name of your choice for the repository. Names are unique across compartments in the regional tenancy namespace. Existing repositories under app/ prevent creation of app with the top-level capability enabled. An existing repository app with the top-level capability enabled also prevents creation of a separate repository named app/backend. Avoid entering confidential information.

      • Tags: Optionally, one or more free-form tags or defined tags to apply to the repository. To apply a defined tag, you must have permissions to use the tag namespace. If you're not sure whether to apply tags, skip this option (you can apply tags later) or ask your administrator. For more information, see Applying Free-form Tags and Defined Tags to Repositories, Images, and Image Signatures.

    3. Select Create.
    4. (Optional) To automatically create new private repositories in the tenancy's root compartment when docker push commands don't include the name of an existing repository, follow these steps:

      1. From the Actions menu, select Edit global policy.

      2. Select Create repository on first push in root compartment.

      3. Select Update.

  • Use the oci artifacts container repository create command and required parameters to create a repository:

    oci artifacts container repository create --display-name <repo-name> --compartment-id <compartment_ocid> [OPTIONS]

    For example:

    oci artifacts container repository create --display-name project01/acme-web-app --compartment-id ocid1.compartment.oc1..aaaaaaaarvdfa72n...

    For a complete list of flags and variable options for CLI commands, see the Command Line Reference.

  • Run the CreateContainerRepository operation to create a repository.