IBM Cloud Docs
Building a container image with stand-alone build commands (CLI)

Building a container image with stand-alone build commands (CLI)

When your code exists as source in a local file or in a Git repository, Code Engine provides options for you to build your code as a container image, per the Open Container Initiative (OCI) standard. With the Code Engine CLI, you can build a container image with a single command.

Code Engine offers the flexibility to handle the build process for you whenever you are deploying your app from repository source code, deploying your app from local source code with the CLI, or you are creating a job from repository source code or creating your job from local source code with the CLI.

However, if you want more control over the build of your container image, Code Engine gives you the flexibility to build your container image by using one of the following options:

  • Use a single CLI command, buildrun submit, to run one build run. The benefit of this option is that you can obtain your build with a single CLI command; however, the configuration for the build is not preserved.
  • Define a build configuration from which you can run multiple build runs. See Building a container image by using a build configuration.

After your build is complete and your image exists, you can deploy the container image as an application or create a job that references your image.

Let's learn about how to build your container image with a single command and not reference a build configuration. In this scenario, IBM Cloud® Code Engine pulls source code from a Git repository or a local directory, builds it, and then pushes (uploads) the container image to a registry. You can choose public or private repositories and registries. You can choose to specify registry details with a registry secret for your build output with user-provided access. Or, you can choose to let Code Engine take care of building the image for you from your source and storing the image in IBM Cloud Container Registry with automatic access.

You can choose to ignore certain file patterns from within your source code by using the .ceignore file, which behaves similarly to a .gitignore file. For example, entries for a .ceignore file for a node.js application might include node_modules and .npm. For more sample file patterns to ignore, see the GitHub .gitignore repository.

Consider the following points before you build your container image:

  • Before you start building images, review planning information. You'll also need to verify that you can access the registry. See Setting up authorities for container registries.

  • If you build multiple versions of the same container image, the latest version of the container image is downloaded and used when you run your job or deploy your application, unless a tag is specified for the image. If a tag is specified for the image, then the tagged image is used for the app or job.

  • Build runs that are submitted with the CLI that do not reference a defined build configuration are also viewable from the console. From the project page, click Image builds to view the list of image builds and build runs. With the CLI, use the ibmcloud ce buildrun list command to view a list of all build runs in a project.

  • Code Engine has quotas for build runs within a project. For more information about Code Engine limits, see Limits and quotas for Code Engine.

Build runs that complete are ultimately automatically deleted. When you run a build run with a single CLI command such that it is not based on a build configuration, this build run is deleted after 1 hour if the build run is successful. If the build run is not successful, this build run is deleted after 24 hours. You can only display information about this build run with the CLI. You cannot view this build run in the console.

Running a single build that pulls source from public repository with the CLI

If your source is located in a public repository and you want to use a single command to build and output a container image, then use the buildrun submit command to create the container image without creating a reusable build configuration.

For the build output, you can choose automatic access and let Code Engine take care of building the image for you from your source and storing the image in IBM Cloud Container Registry. For this case, you do not need to specify a registry secret or the location of the image registry. Or, you can choose user-provided access and specify registry details along with a registry secret to access your built image in the registry.

For a complete listing of options for running a single build, see the ibmcloud ce buildrun submit command.

Running a single build with the CLI (with public repo source and automatic access to registry)

In this automatic access scenario, Code Engine builds an image from your public Git repository source, and uploads the image to IBM Cloud Container Registry with automatic access by using build options with the buildrun submit command. In this case, you do not need to specify a registry secret or the location of the image registry.

See Setting up authorities for image registries for more information about setting required permissions for Code Engine to automatically access these images in Container Registry.

Before you begin

  1. Run a build to build an image from a public Git repo and let Code Engine automatically store and access the image. For example, the following buildrun submit command runs a build run that is called helloworld-buildrun that builds from source in the public Git repo https://github.com/IBM/CodeEngine.

    ibmcloud ce buildrun submit --name helloworld-buildrun --source https://github.com/IBM/CodeEngine --context-dir /hello
    
    • In this example, the command uses the default dockerfile strategy, and the default medium build size.
    • Because the branch name of the repository is not specified with the --commit option, Code Engine automatically uses the default branch of the specified repository, which is main for this Git repo.
    • By not specifying the location of the image registry or a registry secret, Code Engine pushes the build output to IBM Cloud Container Registry with automatic access.
    • Code Engine automatically determines whether your source resides in a repo or on a local workstation, based on the value of the --source option.

    Example output

    Submitting build run 'helloworld-buildrun'...
    Creating image 'private.us.icr.io/ce--12ce3-defg4h5ij6d/buildrun-helloworld-buildrun'...
    Run 'ibmcloud ce buildrun get -n helloworld-buildrun' to check the build run status.
    OK
    

    The following table summarizes the options that are used with the buildrun submit command in this example. For more information about the command and its options, see the ibmcloud ce buildrun submit command.

    Command description
    Option Description
    --name

    The name of the build run. Use a name that is unique within the project.

    • The name must begin and end with a lowercase letter.
    • The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).
    --source The URL of the Git repository or the path to the local source that contains your source code; for example, https://github.com/IBM/CodeEngine.
    --context-dir The directory in the repository that contains the buildpacks file or the Dockerfile. Specify this value if your buildpacks file or Dockerfile is contained in a subdirectory.
  2. Use the buildrun get command to check the status of your build run.

    ibmcloud ce buildrun get -n helloworld-buildrun
    

    Example output

    Notice the generated name for the image and that the name of the automatically created registry secret is of the format, ce-auto-icr-private-<region>.

    Getting build 'helloworld-buildrun'
    For troubleshooting information visit: https://cloud.ibm.com/docs/codeengine?topic=codeengine-troubleshoot-build.
    Run 'ibmcloud ce buildrun events -n helloworld-buildrun' to get the system events of the build run.
    Run 'ibmcloud ce buildrun logs -f -n helloworld-buildrun' to follow the logs of the build run.
    OK
    
    Name:          helloworld-buildrun  
    ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
    Project Name:  myproject  
    Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
    Age:           2d15h
    Created:       2022-06-07T15:30:46-04:00  
    Build Type:    git
    
    Summary:       Succeeded
    Status:        Succeeded
    Reason:        All Steps have completed executing
    Source:
        Commit Branch:  main
        Commit SHA:     946dd18f6e5a5474336786bc28d7dda93aec49c1
        Commit Author:  COMMIT_AUTHOR
    Image Digest:  sha256:ba3c445a27238040e102c083f76ad8922effcc3a7c4dc97b8472e626d87c11a2
    
    Image:              private.us.icr.io/ce--12ce3-defg4h5ij6d/buildrun-helloworld-buildrun
    Registry Secret:    ce-auto-icr-private-us-south
    Build Strategy:     dockerfile-medium
    Timeout:            10m0s
    Source:             https://github.com/IBM/CodeEngine
    Commit:             main
    Context Directory:  /hello
    Dockerfile:         Dockerfile
    

Running a single build with the CLI (with public repo source and user-provided access to registry)

In this user-provided access scenario, Code Engine builds an image from your public Git repository source, and then uploads the image to your container registry with the registry access that you provide with a single build command.

Before you begin

  1. Run a build to build an image from a public Git repo and specify the location of the image registry for the build output with a registry secret. For example, the following buildrun submit command runs a build run that is called helloworld-buildrun2 that builds from the public Git repo https://github.com/IBM/CodeEngine, and stores the image to the us.icr.io/mynamespace/codeengine-helloworld registry by using the myregistry registry secret to access this registry.

    ibmcloud ce buildrun submit --name helloworld-buildrun2 --image us.icr.io/mynamespace/codeengine-helloworld --registry-secret myregistry --source https://github.com/IBM/CodeEngine --context-dir /hello
    
    • In this example, the command uses the default dockerfile strategy, and the default medium build size.
    • Because the branch name of the repository is not specified with the --commit option, Code Engine automatically uses the default branch of the specified repository, which is main for this Git repo.
    • If you are using the --strategy option with the value of dockerfile, then ensure the --dockerfile option is correctly set to the name of the dockerfile. The default value for the --strategy option is Dockerfile.
    • Code Engine automatically determines whether your source resides in a repo or on a local workstation, based on the value of the --source option.

    Example output

    Submitting build run 'helloworld-buildrun2'...
    Creating image 'us.icr.io/mynamespace/codeengine-helloworld'...
    Run 'ibmcloud ce buildrun get -n helloworld-buildrun2' to check the build run status.
    OK
    

    The following table summarizes the options that are used with the buildrun submit command in this example. For more information about the command and its options, see the ibmcloud ce buildrun submit command.

    Command description
    Option Description
    --name

    The name of the build run. Use a name that is unique within the project. This value is required.

    • The name must begin and end with a lowercase letter.
    • The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).
    --image The location of the image registry. The format of the location must be REGISTRY/NAMESPACE/REPOSITORY or REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest.
    --registry-secret The registry secret that is used to access the registry when you create the container image. Run the secret create --format registry command to create a registry secret. The registry secret is used to authenticate with a private registry.
    --source The URL of the Git repository or the path to the local source that contains your source code; for example, https://github.com/IBM/CodeEngine.
    --context-dir The directory in the repository that contains the buildpacks file or the Dockerfile. Specify this value if your buildpacks file or Dockerfile is contained in a subdirectory.
  2. Use the buildrun get command to check the status of your build run.

    ibmcloud ce buildrun get --name helloworld-buildrun2
    

    Example output

    Getting build run 'helloworld-buildrun2'...
    For troubleshooting information visit: https://cloud.ibm.com/docs/codeengine?topic=codeengine-troubleshoot-build.
    Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce buildrun events -n helloworld-buildrun2' to get the system events of the build run.
    Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce buildrun logs -f -n helloworld-buildrun2' to follow the logs of the build run.
    OK
    
    Name:          helloworld-buildrun2  
    ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
    Project Name:  myproject  
    Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
    Age:           2d15h
    Created:       2022-06-07T15:57:43-04:00
    Build Type:    git
    
    Summary:       Succeeded
    Status:        Succeeded
    Reason:        All Steps have completed executing
    Source:
        Commit Branch:  main
        Commit SHA:     946dd18f6e5a5474336786bc28d7dda93aec49c1
        Commit Author:  COMMIT_AUTHOR
    Image Digest:  sha256:6312ee613efa5bec7baa20c47f607e7f15473947d5675fd7384491bee8023afc
    
    Image:              us.icr.io/mynamespace/codeengine-helloworld2
    Registry Secret:    myregistry
    Build Strategy:     dockerfile-medium
    Timeout:            10m0s
    Source:             https://github.com/IBM/CodeEngine
    Context Directory:  /hello
    Dockerfile:         Dockerfile
    

If you receive a command validation failure, check that your secret exists. If you refer to a registry secret (--registry-secret) for your image and the secret does not exist, see Accessing container registries. For more information about builds, check the troubleshooting tips.

Running a single build that pulls source from private repository with the CLI

If your source is located in a private repository and you want to use a single command to build and output a container image, then use the buildrun submit command to create the container image without creating a reusable build configuration.

For the build output, you can choose automatic access and let Code Engine take care of building the image for you from your source and storing the image in IBM Cloud Container Registry. For this case, you do not need to specify a registry secret or the location of the image registry. Or, you can choose user-provided access and specify registry details along with a registry secret to access your built image in the registry.

For a complete listing of options for running a single build, see the ibmcloud ce buildrun submit command.

Running a single build with the CLI (with private repo source and automatic access to registry)

In this automatic access scenario, Code Engine builds an image from your private repository source, and uploads the image to IBM Cloud Container Registry with automatic access by using build options with the buildrun submit command. In this case, you do not need to specify a registry secret or the location of the image registry.

See Setting up authorities for image registries for more information about setting required permissions for Code Engine to automatically access these images in Container Registry.

Before you begin

  1. Run a build to build an image from a private repository and let Code Engine automatically store and access the image. For example, the following buildrun submit command runs a build run that is called helloworld-buildrun-private that builds from the private Git repo https://github.com/myprivaterepo/builds.

    ibmcloud ce buildrun submit --name helloworld-buildrun-private --source git@github.com:myprivaterepo/builds.git --context-dir /hello --strategy buildpacks --git-repo-secret myrepossh
    
    • This example command uses the buildpacks strategy and medium build size.
    • By not specifying the location of the image registry or a registry secret, Code Engine pushes the build output to IBM Cloud Container Registry with automatic access.
    • Because the source in the specified Git repo is private, access requires an SSH secret. An SSH secret is also used as a Git repository access secret. As a result, the --source that you specify must use the SSH protocol, such as git@github.com:myprivaterepo/builds.git. The value for --source must not use the http or https format.
    • Because the branch name of the repository is not specified with the --commit option, Code Engine automatically uses the default branch of the specified repository.
    • Code Engine automatically determines whether your source resides in a repo or on a local workstation, based on the value of the --source option.

    The following table summarizes the options that are used with the buildrun submit command in this example. For more information about the command and its options, see the ibmcloud ce buildrun submit command.

    Command description
    Option Description
    --name

    The name of the build run. Use a name that is unique within the project. This value is required.

    • The name must begin and end with a lowercase letter.
    • The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).
    --source The URL of the Git repository or the path to the local source that contains your source code; for example, git@github.com:myprivaterepo/builds.git.
    --context-dir The directory in the repository that contains the buildpacks file or the Dockerfile. Specify this value if your buildpacks file or Dockerfile is contained in a subdirectory.
    --strategy The strategy to use for building the image. Valid values are dockerfile and buildpacks.
    --git-repo-secret The name of the SSH secret, which contains the credentials to access the private repository that contains the source code to build your container image. Run the secret create --ssh command to create this secret. An SSH secret is also used as a Git repository access secret.
  2. Use the buildrun get command to check the status of your build run.

    ibmcloud ce buildrun get --name helloworld-buildrun-private
    

    Example output

    Getting build run 'helloworld-buildrun-private'...
    For troubleshooting information visit: https://cloud.ibm.com/docs/codeengine?topic=codeengine-troubleshoot-build.
    Run 'ibmcloud ce buildrun events -n helloworld-buildrun-private' to get the system events of the build run.
    Run 'ibmcloud ce buildrun logs -f -n helloworld-buildrun-private' to follow the logs of the build run.
    OK
    
    Name:          helloworld-buildrun-private  
    ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
    Project Name:  myproject  
    Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
    Age:           2d15h
    Created:       2022-06-08T06:02:36-05:00  
    Build Type:    git  
    
    Summary:       Succeeded  
    Status:        Succeeded  
    Reason:        All Steps have completed executing   
    Source:          
        Commit Branch:  main  
        Commit SHA:     946dd18f6e5a5474336786bc28d7dda93aec49c1  
        Commit Author:  COMMIT_AUTHOR  
    Image Digest:  sha256:39c4a87bc43102c2ee88562072c57c135b8dcc5cc4a1104e1d782fe3acc5d5b6  
    Image:              private.us.icr.io/ce--e97a8-odof2whblw5/build-helloworld-buildrun-private
    Registry Secret:    ce-auto-icr-private-us-south  
    Build Strategy:     buildpacks-v3-medium
    Timeout:            10m0s
    Source:             git@github.com:myprivaterepo/builds.git  
    Context Directory:  /hello  
    Repo Secret:        myrepossh
    

Running a single build with the CLI (with private repo source and and user-provided access to registry)

In this user-provided access scenario, Code Engine builds an image from your private repository source with a Git repository secret that you provide, and then uploads the image to your container registry with the registry access that you provide with a single build command.

Before you begin

  1. Run a build to build an image from a private repo and specify the location of the image registry for the build output with a registry secret. The following example buildrun submit command runs a build run that is called helloworld-buildrun-private2 that builds from the private Git repo https://github.com/myprivaterepo/builds, and stores the image to us.icr.io/mynamespace/codeengine-helloworld by using the myregistry registry secret to access this registry.

    ibmcloud ce buildrun submit --name helloworld-buildrun-private2 --image us.icr.io/mynamespace/codeengine-helloworld --registry-secret myregistry --source git@github.com:myprivaterepo/builds.git --context-dir /hello --strategy buildpacks --git-repo-secret myrepossh
    
    • This example command uses the buildpacks strategy and the default medium build size.
    • Because the Git repo provided is private, access requires an SSH secret. An SSH secret is also used as a Git repository access secret. As a result, the --source that you specify must use the SSH protocol, such as git@github.com:myprivaterepo/builds.git. The value for --source must not use the http or https format.
    • Because the branch name of the repository is not specified with the --commit option, Code Engine automatically uses the default branch of the specified repository.
    • Code Engine automatically determines whether your source resides in a repo or on a local workstation, based on the value of the --source option.

    The following table summarizes the options that are used with the buildrun submit command in this example. For more information about the command and its options, see the ibmcloud ce buildrun submit command.

    Command description
    Option Description
    --name

    The name of the build run. Use a name that is unique within the project. This value is required.

    • The name must begin and end with a lowercase letter.
    • The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).
    --image The location of the image registry. The format of the location must be REGISTRY/NAMESPACE/REPOSITORY or REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest.
    --registry-secret The registry secret that is used to access the registry when you create the container image. Run the secret create --format registry command to create a registry secret. The registry secret is used to authenticate with a private registry.
    --source The URL of the Git repository or the path to the local source that contains your source code; for example, git@github.com:myprivaterepo/builds.git.
    --context-dir The directory in the repository that contains the buildpacks file or the Dockerfile. Specify this value if your buildpacks file or Dockerfile is contained in a subdirectory.
    --strategy The strategy to use for building the image. Valid values are dockerfile and buildpacks.
    --git-repo-secret The name of the SSH secret, which contains the credentials to access the private repository that contains the source code to build your container image. Run the secret create --ssh command to create this secret. An SSH secret is also used as a Git repository access secret.
  2. Use the buildrun get command to check the status of your build run.

    ibmcloud ce buildrun get --name helloworld-buildrun-private2
    

    Example output

    Getting build run 'helloworld-buildrun-private2'...
    For troubleshooting information visit: https://cloud.ibm.com/docs/codeengine?topic=codeengine-troubleshoot-build.
    Run 'ibmcloud ce buildrun events -n helloworld-buildrun-private2' to get the system events of the build run.
    Run 'ibmcloud ce buildrun logs -f -n helloworld-buildrun-private2' to follow the logs of the build run.
    OK
    
    Name:          helloworld-buildrun-private2  
    ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
    Project Name:  myproject  
    Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
    Age:           2d10h
    Created:       2022-06-08T06:11:05-05:00  
    Build Type:    git  
    
    Summary:       Succeeded  
    Status:        Succeeded  
    Reason:        All Steps have completed executing  
    Source:          
        Commit Branch:  main  
        Commit SHA:     946dd18f6e5a5474336786bc28d7dda93aec49c1  
        Commit Author:  COMMIT_AUTHOR  
    Image Digest:  sha256:39c4a87bc43102c2ee88562072c57c135b8dcc5cc4a1104e1d782fe3acc5d5b6  
    
    Image:              us.icr.io/mynamespace/codeengine-helloworld  
    Registry Secret:    myregistry  
    Build Strategy:     buildpacks-v3-medium  
    Timeout:            10m0s  
    Source:             git@github.com:myprivaterepo/builds.git  
    Context Directory:  /hello  
    Repo Secret:        myrepossh
    

Running a single build that pulls source from a local directory

If your source is on your local workstation, and you want to use a single command to build and output a container image, then use the buildrun submit command to create the container image without creating a reusable build configuration.

For the build output, you can choose automatic access and let Code Engine take care of building the image for you from your source and storing the image in IBM Cloud Container Registry. For this case, you do not need to specify a registry secret or the location of the image registry. Or, you can choose user-provided access and specify registry details along with a registry secret to access your built image in the registry.

When you submit a build that pulls code from a local directory, your source code is packed into an archive file and uploaded to your IBM Cloud Container Registry instance. Note that you can only target IBM Cloud Container Registry for your local builds. The source image is created in the same namespace as your build image.

You can choose to ignore certain file patterns from within your source code by using the .ceignore file, which behaves similarly to a .gitignore file. For example, entries for a .ceignore file for a node.js application might include node_modules and .npm. For more sample file patterns to ignore, see the GitHub .gitignore repository.

For a complete listing of options for running a single build, see the ibmcloud ce buildrun submit command.

Running a single build with the CLI (with local source and automatic access to registry)

In this automatic access scenario, Code Engine builds an image from your local source, and automatically uploads the image to IBM Cloud Container Registry with automatic access by using build options with the buildrun submit command.

See Setting up authorities for image registries for more information about setting required permissions for Code Engine to automatically access these images in Container Registry. In this case, you do not need to specify a registry secret or the location of the image registry.

Before you begin

Before you work with local source, make sure that your source is in an accessible location on your local workstation.

This example uses the https://github.com/IBM/CodeEngine samples; in particular, the helloworld sample.

  1. Download the https://github.com/IBM/CodeEngine sample source to your local workstation with the following command.

    git clone https://github.com/IBM/CodeEngine
    
  2. Change to the CodeEngine\helloworld directory.

  3. From the CodeEngine\helloworld directory, run a build to build an image from the helloworld source on your local workstation and let Code Engine automatically store and access the image. This command automatically builds and pushes the image to a Container Registry namespace in your account. If you do not have an existing Container Registry namespace, Code Engine automatically creates one for you. For example, the following buildrun submit command runs a build run that is called buildrun-local-dockerfile that builds from the local source.

    ibmcloud ce buildrun submit --name buildrun-local-dockerfile --source .
    

    The . indicates the build source is located in your current working directory.

    • This example command uses the default dockerfile strategy, and the default medium build size.
    • By not specifying the location of the image registry or a registry secret, Code Engine pushes the build output to IBM Cloud Container Registry with automatic access.
    • Code Engine automatically determines whether your source resides in a repo or on a local workstation, based on the value of the --source option.

    Example output

    Packaging files to upload from source path '.'...
    Submitting build run 'buildrun-local-dockerfile'...
    Creating image 'private.us.icr.io/ce--27fe9-glxo4k7nj7d/buildrun-buildrun-local-dockerfile'...
    Run 'ibmcloud ce buildrun get -n buildrun-local-dockerfile' to check the build run status.
    OK
    

    The following table summarizes the options that are used with the buildrun submit command in this example. For more information about the command and its options, see the ibmcloud ce buildrun submit command.

    Command description
    Option Description
    --name

    The name of the build run. Use a name that is unique within the project. This value is required.

    • The name must begin and end with a lowercase letter.
    • The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).
    --source The path to the local source that contains your source code or the URL of the Git repository; for example, ..
  4. Use the buildrun get command to check the status of your build run.

    ibmcloud ce buildrun get --name buildrun-local-dockerfile
    

    Example output

    Getting build run 'buildrun-local-dockerfile'...
    For troubleshooting information visit: https://cloud.ibm.com/docs/codeengine?topic=codeengine-troubleshoot-build.
    Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce buildrun events -n buildrun-local-dockerfile' to get the system events of the build run.
    Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce buildrun logs -f -n buildrun-local-dockerfile' to follow the logs of the build run.
    OK
    
    Name:          buildrun-local-dockerfile  
    ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
    Project Name:  myproject  
    Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
    Age:           2d15h
    Created:       2022-06-07T16:09:34-04:00
    Build Type:    local
    
    Summary:       Succeeded
    Status:        Succeeded
    Reason:        All Steps have completed executing
    Source:
        Source Image Digest:  sha256:ced7abc34f018941145efb56e9a0c1fca99236653c2a05dd5b8b985928ff5f4f
    Image Digest:  sha256:6459430ff49436494aa5e3103eaac98ad90ea50df88a2e14af6314fe88f3c952
    
    Image:                   private.us.icr.io/ce--27fe9-glxo4k7nj7d/buildrun-buildrun-local-dockerfile
    Registry Secret:         ce-auto-icr-private-us-south
    Build Strategy:          dockerfile-medium
    Timeout:                 10m0s
    Source Image:            private.us.icr.io/ce--27fe9-glxo4k7nj7d/buildrun-buildrun-local-dockerfile-source
    Source Registry Secret:  ce-auto-icr-private-us-south
    Dockerfile:              Dockerfile
    

    Notice the generated name for the image and that the name of the automatically created registry secret is of the format, ce-auto-icr-private-<region>.

Running a single build with the CLI (with local source and user-provided access to registry)

In this user-provided access scenario, Code Engine builds an image from your local source, and then uploads the image to your container registry with the registry access that you provide with the buildrun submit command.

Before you begin

Before you work with local source, make sure that your source is in an accessible location on your local workstation.

This example uses the https://github.com/IBM/CodeEngine samples; in particular, the helloworld sample.

  1. Download the https://github.com/IBM/CodeEngine sample source to your local workstation with the following command.

    git clone https://github.com/IBM/CodeEngine
    
  2. Change to the CodeEngine\helloworld directory.

  3. From the CodeEngine\helloworld directory, run a build run to build an image from the helloworld source on your local workstation and specify the location of the image registry for the build output with a registry secret. This buildrun submit command automatically builds and pushes the image to the registry that you specify with the --image option. Specify the --registry-secret option to access your registry.

    ibmcloud ce buildrun submit --name buildrun-local-dockerfile2 --source . --image us.icr.io/mynamespace/codeengine-helloworld --registry-secret myregistry 
    

    The . indicates the build source is located in your current working directory.

    • Code Engine automatically determines whether your source resides in a repo or on a local workstation, based on the value of the --source option.
    • In this example, the command uses the default dockerfile strategy, and the default medium build size.

    The following table summarizes the options that are used with the buildrun submit command in this example. For more information about the command and its options, see the ibmcloud ce buildrun submit command.

    Command description
    Option Description
    --name

    The name of the build run. Use a name that is unique within the project. This value is required.

    • The name must begin and end with a lowercase letter.
    • The name must be 63 characters or fewer and can contain lowercase alphanumeric characters and hyphens (-).
    --source The path to the local source that contains your source code or the URL of the Git repository; for example, ..
    --image The location of the image registry. The format of the location must be REGISTRY/NAMESPACE/REPOSITORY or REGISTRY/NAMESPACE/REPOSITORY:TAG where TAG is optional. If TAG is not specified, the default is latest.
    --registry-secret The registry secret that is used to access the registry when you create the container image. Run the secret create --format registry command to create a registry secret. The registry secret is used to authenticate with a private registry.
  4. Use the buildrun get command to check the status of your build run.

    ibmcloud ce buildrun get --name buildrun-local-dockerfile2
    

    Example output

    Getting build run 'buildrun-local-dockerfile2'...
    For troubleshooting information visit: https://cloud.ibm.com/docs/codeengine?topic=codeengine-troubleshoot-build.
    Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce buildrun events -n buildrun-local-dockerfile2' to get the system events of the build run.
    Run 'C:\Program Files\IBM\Cloud\bin\ibmcloud.exe ce buildrun logs -f -n buildrun-local-dockerfile2' to follow the logs of the build run.
    OK
    
    Name:          buildrun-local-dockerfile2  
    ID:            abcdefgh-abcd-abcd-abcd-1a2b3c4d5e6f  
    Project Name:  myproject  
    Project ID:    01234567-abcd-abcd-abcd-abcdabcd1111 
    Age:           2d15h
    Created:       2022-06-07T16:34:42-04:00
    Build Type:    local
    
    Summary:       Succeeded
    Status:        Succeeded
    Reason:        All Steps have completed executing
    Source:
        Source Image Digest:  sha256:00fb80a8cdc17394ccae564efceb81f48c2cbcbd76afd0fb0b74019352933a63
    Image Digest:  sha256:25bc4bedccc1b34c98ccd92368246df3e61a7cf0cf4915a32f111669b60e2fea
    
    Image:                   us.icr.io/mynamespace/codeengine-helloworld
    Registry Secret:         myregistry
    Build Strategy:          dockerfile-medium
    Timeout:                 10m0s
    Source Image:            us.icr.io/mynamespace/codeengine-helloworld-source
    Source Registry Secret:  myregistry
    Dockerfile:              Dockerfile
    

Next steps for builds

Now that you have built a container image from your source, you can now create an application or job that uses your container image. See Deploying applications and Running jobs.

Looking for more code examples? Check out the Samples for IBM Cloud Code Engine GitHub repo.