Jobs syntax defines individual job configuration within CloudBees Unify workflows including execution environment, dependencies, permissions, and job-level properties. Use this reference when configuring job behavior, dependencies, and execution context.
Job definition
jobs.<job_id>
Defines a job within the workflow. Each job runs in a fresh execution environment.
jobs: build: # Job configuration test: # Job configuration deploy: # Job configuration
Job identifiers must:
-
Start with a letter or underscore
-
Contain only alphanumeric characters, hyphens, and underscores
-
Be unique within the workflow
Job configuration properties
delegates
Specifies delegation configuration for the job execution environment.
jobs: build: delegates: - type: 'kubernetes' spec: namespace: 'default'
Properties:
type-
Delegation type (kubernetes, docker, etc.)
spec-
Delegation-specific configuration object
env
Sets environment variables for all steps in the job.
jobs: build: env: NODE_VERSION: '18' BUILD_ENV: 'production' API_TOKEN: ${{ secrets.API_TOKEN }}
Environment variables can reference contexts and secrets using expression syntax.
vars
Defines variables accessible within the job context.
jobs: build: vars: build-version: '1.2.3' config-file: 'config/prod.json'
Variables are accessible through the vars context in steps.
environment
Specifies the deployment environment for the job.
jobs: deploy: environment: production
Or with environment-specific configuration:
jobs: deploy: environment: name: production url: https://prod.example.com
Properties:
name-
Environment name
url-
Environment URL for reference
if
Conditional expression that determines whether the job runs.
jobs: deploy: if: ${{ success() && github.ref == 'refs/heads/main' }}
Common conditional patterns:
# Run on success only if: ${{ success() }} # Run on specific branch if: ${{ github.ref == 'refs/heads/main' }} # Run on pull request if: ${{ github.event_name == 'pull_request' }} # Run when environment variable is set if: ${{ env.DEPLOY_ENABLED == 'true' }} # Run on failure of previous jobs if: ${{ failure() }}
needs
Defines job dependencies. Jobs with dependencies wait for needed jobs to complete successfully before starting.
jobs: build: # No dependencies test: needs: build deploy: needs: [build, test]
Access outputs from needed jobs:
jobs: build: outputs: version: ${{ steps.version.outputs.value }} deploy: needs: build steps: - name: Deploy version run: echo "Deploying ${{ needs.build.outputs.version }}"
outputs
Defines job outputs accessible to dependent jobs.
jobs: build: outputs: version: ${{ steps.version.outputs.version }} artifact-url: ${{ steps.upload.outputs.url }} steps: - id: version run: echo "version=1.2.3" >> $CLOUDBEES_OUTPUTS - id: upload # Upload step
Output values:
-
Must be set by steps within the job using step outputs
-
Are accessible to jobs that depend on this job via
needs.<job_id>.outputs.<output_name> -
Can reference step outputs using
steps.<step_id>.outputs.<output_name>
permissions
Overrides workflow-level permissions for this specific job.
jobs: security-scan: permissions: contents: read security-events: write actions: read
Available permissions: Same as workflow-level permissions. Job-level permissions take precedence over workflow-level permissions for that job only.
secrets
Makes secrets available to the job context.
jobs: deploy: secrets: api-token: ${{ secrets.PROD_API_TOKEN }} ssh-key: ${{ secrets.DEPLOY_SSH_KEY }}
Secrets are accessible in steps via the secrets context:
steps: - name: Deploy env: API_TOKEN: ${{ secrets.api-token }} run: ./deploy.sh
timeout-minutes
Sets the maximum execution time for the job in minutes.
jobs: build: timeout-minutes: 60
Properties:
-
Default timeout: 5760 minutes (4 days)
-
Valid range: 1-1440 minutes (24 hours)
-
Job is cancelled if timeout is exceeded
uses
Specifies a reusable workflow to execute.
jobs: call-workflow: uses: ./.cloudbees/workflows/shared-build.yml with: node-version: '18' environment: 'staging' secrets: api-token: ${{ secrets.API_TOKEN }}
Properties:
with-
Input parameters passed to the reusable workflow
secrets-
Secrets passed to the reusable workflow
Reusable workflow paths:
-
Relative path:
./.cloudbees/workflows/workflow.yml -
Repository reference:
owner/repo/.cloudbees/workflows/workflow.yml@ref
Job dependency patterns
Sequential execution
jobs: build: steps: [...] test: needs: build steps: [...] deploy: needs: test steps: [...]
Parallel execution with final job
jobs: unit-tests: steps: [...] integration-tests: steps: [...] lint: steps: [...] deploy: needs: [unit-tests, integration-tests, lint] steps: [...]
Conditional dependencies
jobs: build: steps: [...] test: needs: build steps: [...] deploy-staging: needs: test if: ${{ github.ref == 'refs/heads/develop' }} steps: [...] deploy-production: needs: test if: ${{ github.ref == 'refs/heads/main' }} steps: [...]
Fan-out/fan-in pattern
jobs: setup: outputs: matrix: ${{ steps.matrix.outputs.value }} steps: [...] build: needs: setup strategy: matrix: ${{ fromJson(needs.setup.outputs.matrix) }} steps: [...] test: needs: setup strategy: matrix: ${{ fromJson(needs.setup.outputs.matrix) }} steps: [...] deploy: needs: [build, test] steps: [...]