---
name: codeengine-appdeploy-cr
title: Deploying app workloads from images in IBM Cloud Container Registry
description: Deploy your app with Code Engine that uses an image in IBM Cloud® Container Registry. You can create an app from the console or with the CLI.
last-updated: 2026-07-08
---

> ## Documentation Index
> The table of contents for this documentation set is at https://cloud.ibm.com/docs/codeengine?format=markdown
> The index for all IBM Cloud docs is at: https://cloud.ibm.com/docs/llms.txt
> Use these files to discover more information as needed.

# Deploying app workloads from images in IBM Cloud Container Registry
{: #deploy-app-crimage}

Deploy your app with Code Engine that uses an image in IBM Cloud® Container Registry. You can create an app from the console or with the CLI.
{: shortdesc}

Before you begin

- You must have an image in IBM Cloud® Container Registry. For more information, see [Getting started with Container Registry](https://cloud.ibm.com/docs/Registry?topic=Registry-getting-started&format=markdown#getting-started). Or, you can build an image from [repository source](https://cloud.ibm.com/docs/codeengine?topic=codeengine-app-source-code&format=markdown) or from [local source](https://cloud.ibm.com/docs/codeengine?topic=codeengine-app-local-source-code&format=markdown).

- Verify that you can access the registry. See [Setting up authorities for container registries](https://cloud.ibm.com/docs/codeengine?topic=codeengine-add-registry&format=markdown#authorities-registry).

Interested in configuring your project such that all users of the project can store and access images in Container Registry without having to manually create registry secrets? With sufficient permissions, you can configure this default registry access on a per location (region) basis. If you don't have sufficient permissions to perform these actions, you can use this page to help you understand the required permissions. See [Configuring project-wide settings](https://cloud.ibm.com/docs/codeengine?topic=codeengine-project-integrations&format=markdown). 
{: note}


## Deploying an app that references an image in Container Registry with the console
{: #deploy-app-crimage-console}

Deploy an application that uses an image in Container Registry by using the Code Engine console.
{: shortdesc}

Code Engine can automatically pull images from a Container Registry namespace in your account. To pull images from a different Container Registry account or from a private Docker Hub account, see [Deploying application workloads from images in a private registry](https://cloud.ibm.com/docs/codeengine?topic=codeengine-deploy-app-private&format=markdown).

1. Open the [Code Engine](https://cloud.ibm.com/codeengine/overview){: external} console.
2. Select **Start creating**.
3. Select a project from the list of available projects. You can also [create a new one](https://cloud.ibm.com/docs/codeengine?topic=codeengine-manage-project&format=markdown#create-a-project). You must have a selected project to deploy an app.
4. Select **Application**.
5. Enter a name for the application; for example, `helloapp`. Use a name for your application that is unique within the project.
6. Select **Use an existing container image** and click **Configure image**.
7. Select a container registry location, such as `IBM Registry Dallas`.
8. Select `Code Engine managed secret` for **Registry secret**. Because this example uses an image in a Container Registry namespace in your account, Code Engine can automatically create and manage the registry secret for you.
9. Select an existing namespace and name of the image in the registry for the Code Engine app to reference. For example, select `mynamespace` and select the image `hello_repo` in that namespace.
10. Select a value for **Tag**; for example, `latest`.
11. Click **Done**.
12. Modify any runtime settings or environment variables for your app. For more information about these options, see [Options for endpoint visibility of apps](https://cloud.ibm.com/docs/codeengine?topic=codeengine-application-workloads&format=markdown#optionsdeploy) and [Options for deploying an app](https://cloud.ibm.com/docs/codeengine?topic=codeengine-application-workloads&format=markdown#optionsdeploy).
13. Click **Create** to create the application.
14. After the application status changes to **Ready**, you can test the application. Click **Test application** and then click **Send request** in the Test application pane. To open the application in a web page, click **Application URL**.

Now that you have deployed your application, you can view information about application revisions and any running instances, and configuration details.  



If you want to add registry access to a Container Registry instance that is not in your account, see [Adding access to a Container Registry](https://cloud.ibm.com/docs/codeengine?topic=codeengine-add-registry&format=markdown).




## Deploying an app with an image in Container Registry with the CLI
{: #deploy-app-crimage-cli}

Deploy an application that uses an image in IBM Cloud® Container Registry with the CLI with the **`ibmcloud ce app create`** command. For a complete listing of options, see the [**`ibmcloud ce app create`**](https://cloud.ibm.com/docs/codeengine?topic=codeengine-cli&format=markdown#cli-application-create) command.
{: shortdesc}

Before you begin

* Set up your [Code Engine CLI](https://cloud.ibm.com/docs/codeengine?topic=codeengine-install-cli&format=markdown) environment.
* [Create and work with a project](https://cloud.ibm.com/docs/codeengine?topic=codeengine-manage-project&format=markdown).
* Before you can work with a Code Engine application that references an image in Container Registry, you must first add access to the registry so Code Engine can pull the image when the app is deployed. For information about required permissions for accessing image registries, see [Setting up authorities for image registries](https://cloud.ibm.com/docs/codeengine?topic=codeengine-add-registry&format=markdown#authorities-registry).

1. To add access to Container Registry, [create an IAM API key](https://cloud.ibm.com/docs/codeengine?topic=codeengine-add-registry&format=markdown#images-your-account-api-key). To create an IBM Cloud IAM API key with the CLI, run the [**`iam api-key-create`**](https://cloud.ibm.com/docs/iam?topic=iam-ibmcloud_commands_iam&format=markdown#ibmcloud_iam_api_key_create) command. For example, to create an API key called `cliapikey` with a description of `My CLI API key` and save it to a file called `key_file`, run the following command:

    ```txt
    ibmcloud iam api-key-create cliapikey -d "My CLI API key" --file key_file
    ```
    {: pre}

    If you choose to not save your key to a file, you must record the API key that is displayed when you create it. You cannot retrieve it later.
    {: important}

2. After you create your API key, add registry access to Code Engine. To add access to Container Registry with the CLI, use the [**`ibmcloud ce secret create --format registry`**](https://cloud.ibm.com/docs/codeengine?topic=codeengine-cli&format=markdown#cli-secret-create) command to create a registry secret. For example, the following command creates registry access to a Container Registry instance called `myregistry`. Note, even though the `--server` and `--username` options are specified in the example command, the default value for the `--server` option is `us.icr.io` and the `--username` option defaults to `iamapikey` when the server is `us.icr.io`.

    ```txt
    ibmcloud ce secret create --format registry --name myregistry --server us.icr.io --username iamapikey --password APIKEY
    ```
    {: pre}

    Example output

    ```txt
    Creating registry secret 'myregistry'...
    OK
    ```
    {: screen}

3. Create your app and reference the `hello_repo` image in Container Registry. For example, use the [**`ibmcloud ce app create`**](https://cloud.ibm.com/docs/codeengine?topic=codeengine-cli&format=markdown#cli-application-create) command to create the `myhelloapp` app to reference the `us.icr.io/mynamespace/hello_repo` by using the `myregistry` access information.

    ```txt
    ibmcloud ce app create --name myhelloapp --image us.icr.io/mynamespace/hello_repo --registry-secret myregistry
    ```
    {: pre}

    The format of the name of the image for this application is `REGISTRY/NAMESPACE/REPOSITORY:TAG` where `REGISTRY` and `TAG` are optional. If `REGISTRY` is not specified, the default is `docker.io`. If `TAG` is not specified, the default is `latest`.
    {: important}

4. After your app deploys, you can access the app. To obtain the URL of your app, run `ibmcloud ce app get --name myhelloapp --output url`. When you curl the `myhelloapp` app, `Hello World` is returned.

    ```txt
    curl https://myhelloapp.abcdabcdhye.us-south.codeengine.appdomain.cloud
    ```
    {: pre}


## Next steps
{: #nextsteps-appdeploycr}

* After your app deploys, [access your app](https://cloud.ibm.com/docs/codeengine?topic=codeengine-access-service&format=markdown) through a URL.

* You can create a [custom domain mapping](https://cloud.ibm.com/docs/codeengine?topic=codeengine-domain-mappings&format=markdown) and assign it to your app. For more information about deploying apps across multiple regions with a custom domain name, see [Configuring a highly available application](https://cloud.ibm.com/docs/codeengine?topic=codeengine-deploy-multiple-regions&format=markdown). 

* Now that your app is deployed, consider making your apps event-driven. By using event subscriptions, you can trigger your apps by [periodic schedules](https://cloud.ibm.com/docs/codeengine?topic=codeengine-subscribe-cron&format=markdown#eventing-cron-existing-app) or set your app to react to events such as [file uploads](https://cloud.ibm.com/docs/codeengine?topic=codeengine-eventing-cosevent-producer&format=markdown#obstorage_ev_app) or [Kafka messages](https://cloud.ibm.com/docs/codeengine?topic=codeengine-working-kafkaevent-producer&format=markdown).

After your app is deployed, you can [update your deployed app](https://cloud.ibm.com/docs/codeengine?topic=codeengine-update-app&format=markdown) and its referenced code by using *any* of the following ways, independent of how you created or previously updated your app:

- If you have a container image, per the [Open Container Initiative (OCI) standard](https://opencontainers.org/){: external}, then you need to provide only a reference to the image, which points to the location of your container registry when you deploy your app. You can deploy your app with an image in a [public registry](https://cloud.ibm.com/docs/codeengine?topic=codeengine-deploy-app&format=markdown) or [private registry](https://cloud.ibm.com/docs/codeengine?topic=codeengine-deploy-app-private&format=markdown).

    If you created your app by using the **`app create`** command and you specified the `--build-source` option to build the container image from local or repository source, and you want to change your app to point to a different container image, you must first remove the association of the build from your app. For example, run `ibmcloud ce application update -n APP_NAME --build-clear`. After you remove the association of the build from your app, you can update the app to reference a different image. 
    {: important}

- If you are starting with source code that resides in a Git repository, you can choose to let Code Engine take care of building the image from your source and deploying the app with a **single** operation. In this scenario, Code Engine uploads your image to IBM Cloud® Container Registry. To learn more, see [Deploying your app from repository source code](https://cloud.ibm.com/docs/codeengine?topic=codeengine-app-source-code&format=markdown). If you want more control over the build of your image, then you can choose to [build the image](https://cloud.ibm.com/docs/codeengine?topic=codeengine-plan-build&format=markdown) with Code Engine before you deploy your app. 

- If you are starting with source code that resides on a local workstation, you can choose to let Code Engine take care of building the image from your source and deploying the app with a **single** CLI command. In this scenario, Code Engine uploads your image to IBM Cloud® Container Registry. To learn more, see [Deploying your app from local source code with the CLI](https://cloud.ibm.com/docs/codeengine?topic=codeengine-app-local-source-code&format=markdown). If you want more control over the build of your image, then you can choose to [build the image](https://cloud.ibm.com/docs/codeengine?topic=codeengine-plan-build&format=markdown) with Code Engine before you deploy your app. 

    For example, you might choose to let Code Engine handle the build of your local source while you evolve the development of your source for the app. Then, after the image is matured, you can update the deployed app to reference the specific image that you want. You can repeat this process as needed.

When you deploy your updated app, the latest version of your referenced container image is downloaded and deployed, unless a tag is specified for the image. If a tag is specified for the image, then the tagged image is used for the deployment. 




Looking for more code examples? Check out the [Samples for IBM Cloud Code Engine GitHub repo](https://github.com/IBM/CodeEngine){: external}.
{: tip}