Steps syntax reference

Steps syntax defines individual step configuration within CloudBees Unify job execution including actions, commands, conditionals, and step-level properties. Use this reference when configuring step behavior, action usage, and step execution context.

Steps execute in containers that share the same job workspace directory. Because step commands run in their own containers, any changes to environment variables or other local filesystem directories are not saved as the workflow runs from step to step.

Steps definition

`jobs.<job_id>.steps`

Defines the sequence of steps that make up a job. Steps run sequentially in the order defined.

jobs:
  build:
    steps:
      - name: Checkout code
        uses: cloudbees-io/checkout@v1
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      - name: Install dependencies
        run: npm install
      - name: Run tests
        run: npm test▼

Step configuration properties

`continue-on-error`

Determines whether the job continues when this step fails.

steps:
  - name: Optional linting
    run: npm run lint
    continue-on-error: true
  - name: Required tests
    run: npm test▼

Values:

true: Job continues even if this step fails
false: Job fails if this step fails (default)

`env`

Sets environment variables for the step.

steps:
  - name: Build with custom env
    env:
      NODE_ENV: production
      API_URL: https://api.example.com
      SECRET_KEY: ${{ secrets.SECRET_KEY }}
    run: npm run build▼

Step-level environment variables:

Override job-level and workflow-level variables with the same name
Are available only to this specific step
Can reference contexts and secrets

`id`

Assigns a unique identifier to the step for referencing outputs.

steps:
  - id: version
    name: Get version
    run: echo "version=$(cat package.json | jq -r .version)" >> $CLOUDBEES_OUTPUTS
  - name: Use version
    run: echo "Building version ${{ steps.version.outputs.version }}"▼

Step IDs:

Must be unique within the job
Used to access step outputs via steps.<id>.outputs.<name>
Must start with a letter or underscore
Contain only alphanumeric characters, hyphens, and underscores

`if`

Conditional expression that determines whether the step runs.

steps:
  - name: Deploy to production
    if: ${{ success() && cloudbees.scm.ref == 'refs/heads/main' }}
    run: ./deploy.sh production▼

Common conditional patterns:

# Run only on success
if: ${{ success() }}

# Run only on failure
if: ${{ failure() }}

# Always run (even on cancel/failure)
if: ${{ always() }}

# Run on specific conditions
if: ${{ env.DEPLOY_ENABLED == 'true' }}

# Complex conditions
if: ${{ success() && (cloudbees.event_name == 'push' || cloudbees.event_name == 'workflow_dispatch') }}▼

`name`

Provides a human-readable name for the step displayed in logs and UI.

steps:
  - name: Install Node.js dependencies
    run: npm install
  - name: Run unit tests
    run: npm test
  - name: Upload test results
    uses: actions/upload-artifact@v3▼

Step names:

Are displayed in the workflow run UI
Help identify steps in logs and debugging
Should be descriptive and action-oriented

`run`

Executes shell commands in the job’s execution environment.

steps:
  - name: Single command
    run: echo "Hello, World!"

  - name: Multiple commands
    run: |
      echo "Starting build..."
      npm install
      npm run build
      echo "Build complete!"

  - name: Command with variables
    run: |
      echo "Building version ${{ env.VERSION }}"
      ./build.sh --version=${{ env.VERSION }}▼

Command execution:

Commands run in the default shell (bash)
Multi-line commands use YAML literal block scalar (|)
Environment variables and contexts are expanded
Exit code determines step success/failure (0 = success, non-zero = failure)

`shell`

Specifies the shell to use for executing run commands.

steps:
  - name: Bash script
    shell: bash
    run: echo "Using bash shell"

  - name: Python script
    shell: python
    run: |
      import sys
      print(sys.version)▼

Available shells:

bash: Bash shell (all platforms)
sh: POSIX shell (Linux only)
python: Python interpreter (all platforms)

Only Linux platforms are currently supported.

`timeout-minutes`

Sets the maximum execution time for the step in minutes.

steps:
  - name: Long-running task
    run: ./long-task.sh
    timeout-minutes: 30

  - name: Quick task
    run: echo "Quick task"
    timeout-minutes: 1▼

Properties:

Default timeout: Inherits from job timeout
Valid range: 1-1440 minutes (24 hours)
Step is cancelled if timeout is exceeded

`uses`

Specifies an action to execute.

steps:
  - name: Checkout repository
    uses: cloudbees-io/checkout@v1

  - name: Setup Node.js
    uses: actions/setup-node@v3
    with:
      node-version: '18'
      cache: 'npm'

  - name: Custom action
    uses: ./.cloudbees/actions/custom-action
    with:
      input1: value1
      input2: ${{ env.VALUE2 }}▼

Action references:

CloudBees actions: cloudbees-io/action-name@version
GitHub Actions: actions/action-name@version
Local actions: ./.cloudbees/actions/action-name
Repository actions: owner/repo/action-path@ref

`with`

Provides input parameters to actions specified with uses.

steps:
  - name: Setup Node.js with specific version
    uses: actions/setup-node@v3
    with:
      node-version: '18'
      cache: 'npm'
      registry-url: 'https://registry.npmjs.org'

  - name: Custom action with inputs
    uses: my-org/custom-action@v1
    with:
      api-endpoint: ${{ env.API_URL }}
      timeout: '300'
      debug: 'true'▼

Input parameters:

Are defined by the action being used
Can reference contexts, environment variables, and secrets
String values are recommended (actions handle type conversion)
Are passed to the action’s execution environment

When the uses value is a Docker image and with.args is used to pass container arguments:

Enter arguments as a Unicode string; an array of strings is not supported.
Arguments containing spaces must be surrounded by double quotes ("").

Step output management

Setting step outputs

Use the $CLOUDBEES_OUTPUTS environment file to set step outputs.

steps:
  - id: version
    name: Get application version
    run: |
      VERSION=$(cat package.json | jq -r .version)
      echo "version=$VERSION" >> $CLOUDBEES_OUTPUTS
      echo "major=$(echo $VERSION | cut -d. -f1)" >> $CLOUDBEES_OUTPUTS▼

Accessing step outputs

Reference outputs from previous steps using the steps context.

steps:
  - id: build-info
    name: Get build information
    run: |
      echo "build-id=${{ cloudbees.run_id }}" >> $CLOUDBEES_OUTPUTS
      echo "timestamp=$(date -u +%Y%m%d%H%M%S)" >> $CLOUDBEES_OUTPUTS

  - name: Use build information
    run: |
      echo "Build ID: ${{ steps.build-info.outputs.build-id }}"
      echo "Timestamp: ${{ steps.build-info.outputs.timestamp }}"

  - name: Create artifact name
    env:
      ARTIFACT_NAME: "app-${{ steps.build-info.outputs.build-id }}-${{ steps.build-info.outputs.timestamp }}"
    run: echo "Artifact: $ARTIFACT_NAME"▼

Common step patterns

Conditional steps based on previous step results

steps:
  - id: test
    name: Run tests
    run: npm test
    continue-on-error: true

  - name: Handle test success
    if: ${{ steps.test.outcome == 'success' }}
    run: echo "Tests passed!"

  - name: Handle test failure
    if: ${{ steps.test.outcome == 'failure' }}
    run: echo "Tests failed, but continuing..."▼

Multi-step setup and cleanup

steps:
  - name: Setup test environment
    run: |
      docker-compose up -d
      sleep 10  # Wait for services to start

  - name: Run integration tests
    run: npm run test:integration

  - name: Cleanup test environment
    if: ${{ always() }}
    run: docker-compose down▼

Matrix-based steps

jobs:
  test:
    strategy:
      matrix:
        node-version: [16, 18, 20]
        os: [ubuntu-latest, windows-latest]
    steps:
      - name: Setup Node.js ${{ matrix.node-version }}
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}

      - name: Run tests on ${{ matrix.os }}
        run: npm test▼

Artifact handling steps

steps:
  - name: Build application
    run: npm run build

  - name: Upload build artifacts
    uses: actions/upload-artifact@v3
    with:
      name: build-${{ github.run_id }}
      path: dist/

  - name: Download artifacts (in different job)
    uses: actions/download-artifact@v3
    with:
      name: build-${{ github.run_id }}
      path: dist/▼