10.3 Jobs, Steps, Needs, If, Allow Failure

Jobs

A job is a pipeline stage with its own tags, conditions, and steps.

Steps

A step is one command block executed in selected shell. Use multiple small steps instead of one giant command block for better observability.

Needs

needs defines DAG dependencies between jobs.

• Enables serial safety where required.
• Enables parallel execution where possible.

If

if controls conditional execution for job or step.

• Job-level if: gate whole stage.
• Step-level if: gate command subset.

Allow Failure

allow_failure: true marks a job as non-blocking if it fails. Use only for genuinely optional checks.

Operational strategy:

• critical path jobs (backup, deploy, migration) should be strict.
• optional diagnostics/reporting can be allow-failure.

Jobs, Needs, Conditions

Use DAG pipelines for prepare/build/test/deploy flow. Jobs can run in parallel by dependency graph, and you can control behavior on failure using needs_policy, allow_failure, and step-level when.

jobs:
  test:
    needs: [build]
    needs_policy: all_done          # success | all_done
    if: ${{ vars.APP_MODE }} == demo
    allow_failure: true
    steps:
      - name: run-tests
        shell: bash
        run: ./scripts/test.sh

      - name: notify-on-failure
        when: on_failure            # on_success | on_failure | always
        run: echo "tests failed"

      - name: cleanup
        when: always
        run: rm -rf .tmp || true

Artifacts Between Jobs

Artifacts are the standard way to pass files between jobs/agents. Build job uploads output; downstream job reads via needs.<job_key>.artifacts.*.

jobs:
  build:
    steps:
      - name: build
        run: |
          mkdir -p out
          echo "build $(date -u +%Y-%m-%dT%H:%M:%SZ)" > out/build.txt
    artifacts:
      name: build-output
      retention_days: 7
      paths:
        - out/**

  verify:
    needs: [build]
    steps:
      - name: check
        run: |
          ls -la "${{ needs.build.artifacts.dir }}"
          cat "${{ needs.build.artifacts.dir }}/out/build.txt"

Container Execution

Container mode gives isolated, reproducible runtime with resource and security limits. Use for deterministic builds and safer script execution.

jobs:
  smoke:
    tags: [linux]
    container:
      image: alpine:3.20
      pull_policy: if-not-present
      network: bridge
      cpu: "1.0"
      memory: "512m"
      read_only: true
      no_new_privileges: true
      cap_drop: [ALL]
      tmpfs:
        - /tmp:size=64m
    steps:
      - name: ping
        shell: bash
        run: |
          apk add --no-cache iputils
          ping -c 1 1.1.1.1 || true

Timeouts, Retry, Concurrency

Production baseline for stable operations: per-job timeout, per-step timeout/retry, cleanup hooks, and concurrency groups to avoid parallel deploy races to same environment/service.

concurrency:
  group: deploy-prod
  cancel_in_progress: true

jobs:
  deploy:
    timeout_sec: 1800
    teardown_timeout_sec: 120
    steps:
      - name: migrate
        timeout_sec: 300
        retry: 2
        retry_delay_sec: 15
        run: php artisan migrate --force

      - name: restart-workers
        when: always
        run: php artisan horizon:terminate || true