---
title: "Images"
url: https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/build-the-pipeline/images/
description: "Learn about the Catalyst Pipelines images in detail, the associated keywords and sample code snippets."
last_updated: 2026-08-28T06:26:16Z
service: Pipelines
type: general
related_links:
  - name: "Configure the Pipeline"
    url: /en/pipelines/help/catalyst-pipelines.yaml/implementation
---

# Images

# Introduction

An image is an executable package that contains dependencies needed to run a job in the pipeline. Catalyst Pipelines seamlessly integrates with container registries such as Docker Hub or other private registries to pull images and dependencies during the pipeline execution. 

You can pick from a wide range of images supporting varied operating systems, programming languages, frameworks, and tools to suit your specific requirements. Additionally, using predefined images ensures consistency and reproducibility across different stages of the pipeline and environments. 

You can pull images by specifying the container registry URL explicitly using the `registry` key. If the registry URL is not defined, the images are pulled from the [Dockerhub](https://hub.docker.com/) container by default. You can define the required images for the pipeline using the `images` key. 	

### Properties of an Image 

<table class="content-table">
        <thead>
            <tr>
                <th>Key</th>
                <th>Value</th>
                <th>is Mandatory</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Image Variable Name</td>
                <td>The image variable name used to access the image</td>
                <td>Yes</td>
            </tr>
            <tr>
                <td>`image`</td>
                <td>The name of the image</td>
                <td>Yes</td>
            </tr>
            <tr>
                <td>`registry`</td>
                <td>The URL from which the image has to be fetched.</td>
                <td>No</td>
            </tr>
            <tr>
                <td>`auth`</td>
                <td>Contains the username and password keys.</td>
                <td>Yes</td>
            </tr>
            <tr>
                <td>`auth`</td>
                <td>Contains the username and password keys.</td>
                <td>Yes</td>
            </tr>
            <tr>
                <td>`username`</td>
                <td>The account username credential of the specified registry.</td>
                <td>Yes</td>
            </tr>
            <tr>
                <td>`password`</td>
                <td>The account password credential of the specified registry.</td>
                <td>Yes</td>
            </tr>
            </tbody>
</table>

> **Note:**

1. Defining an image is not mandatory. If an image is not specified, the default Ubuntu image with Catalyst CLI pre-installed is taken by default to execute the jobs. 

2. You can define images at the pipeline level, stage level, or job level. In case of multiple definitions, the one specified at the lowest level (i.e., job) takes precedence.

3. If the same image is specified for two jobs within a stage, the cached image will automatically be reused for the second job, enhancing performance speed.

4. If the image name is specified and the registry URL is not given, then make sure to provide the `username` and `password` credentials of your [Dockerhub](https://hub.docker.com/) account in the `auth` key. The image will be pulled from DockerHub by default. 

For security reasons, we highly recommend you store your password information as a variable in the global configuration and access it using `<< env.{variable_name} >>` in the `catalyst-pipelines.yaml` file. You can refer to [this help section](https://docs.catalyst.zoho.com/en/pipelines/help/catalyst-pipelines.yaml/implementation) to learn how to configure variables globally from the console.

### YAML Code Snippet for Image

Here's an example code snippet for images that can be defined in a pipeline:

```yaml
images:
  testImage1:
    image: node:18
    registry: my.private.registry.com
    auth:
      username: ameliab
      password: zylker@123
  testImage2:
    image: node:20
    auth:
      username: ameliab
      password: zylker@123

```

The above code snippet illustrates the following:

* Two images are defined in the pipeline(`testImage1` and `testImage2`). 
* The `testImage1` uses the node18 dependencies from the defined registry URL. We have added the authentication credentials for the registry to the keyword `auth`.
* By default, since the registry is not specified, the `testimage2` uses the **node20** dependencies from [Dockerhub](https://hub.docker.com/).

### Global Configuration 

You can also define the image at the pipeline level, if required. This image configuration will be accessible to all the stages and jobs. You can configure an image at the pipeline level as follows:

```json
 pipeline-image: image1
```