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

Secrets

Secrets are a way to securely store and use sensitive information in your pipelines, such as API keys, signing keys, passwords, or certificates. This information is defined and managed within the HexDroid Web UI and can then be made available to specific stages in your pipeline.

To use a secret in your pipeline, you first need to define it in the HexDroid Web UI (Navigate to "Project Settings → Secrets" to create or update a secret). Refer to Secrets page for more information.

Once defined, you can reference it within a stage's secrets block. This will make the secret accessible as an environment variable to all steps within that particular stage.

For example, let's say you have a my-signing-key secret with the ID (slug) stored in the HexDroid Web UI.

To make its latest version available as an environment variable named MY_SIGNING_KEY within the my_build_job stage, you would configure your pipeline as follows:

stages:
  my_build_job:
    secrets:
      - secret:
          id: my-signing-key # The ID (slug) of the secret defined in HexDroid Web UI
          version: latest # The version of the secret to use or "latest"
          as_env: MY_SIGNING_KEY # The name of the environment variable
    agent:
      container:
        image: ubuntu:latest
    steps:
      # WARNING: DO NOT print raw secret value as it would defeat the purpose of a secret
      - run: "echo $MY_SIGNING_KEY | sha256sum"