Stages

A pipeline consists of one or more stages, where each stage is a collection of steps that are executed serially. Each stage is self-contained, meaning it can run on separate agents (if multiple agents are available), or serially on a single agent with a clean environment between stages.

name: Example
version: 1.0

stages:
  stage_1:
    agent:
      container:
        image: ubuntu:latest
    steps:
      - run: ls -la
  stage_2:
    agent:
      container:
        image: gradle:8-jdk21
    steps:
      - run: java --version

Agent

Each step within a stage is executed inside an isolated environment defined by the agent.
The most common configuration is to specify a container image, which provides a consistent and reproducible runtime for all commands in the stage.

The following example runs all steps of the my_build_job stage inside the ubuntu:latest container:

stages:
  my_build_job:
    agent:
      container:
        image: ubuntu:latest

Container environment

You can also specify environment variables that will be available inside the container.
This can be useful for configuring tools, setting credentials, or controlling runtime behavior.

agent:
  container:
    image: ubuntu:latest
    environment:
      - "MY_ENV_VAR": "hello"

Each key-value pair under the environment is exported as an environment variable inside the container for all steps that run within that stage.

Image pull

By default, HexDroid attempts to pull the container image each time a job is run. This ensures a predictable environment for every pipeline execution.

However, if you wish to override this behavior and disable the automatic pulling of container images, set pull: false in your configuration like this:

stages:
  my_build_job:
    agent:
      container:
        image: ubuntu:latest
        pull: false