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 of a custom job to execute the workflow job.
|
When referring to a file within a repository, the repository clone URL and the repository-internal path must be separated by a double slash For example: https://github.com/myorg/myrepo//path/to/my/file.yaml However, for backward compatibility the double slash |
<job-name>: delegates: <path to any custom job> with: < Use `with` to provide custom job input values>
|
A single workflow job must contain only one of the following execution syntax terms: |
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() && cloudbees.scm.ref == 'refs/heads/main' }}
Common conditional patterns:
# Run on success only if: ${{ success() }} # Run on specific branch if: ${{ cloudbees.scm.ref == 'refs/heads/main' }} # Run on pull request if: ${{ cloudbees.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
Do not combine secrets: inherit and explicit secret mappings in the same job. Choose one approach.
|
timeout-minutes
Sets the maximum execution time for the job in minutes.
jobs: build: timeout-minutes: 60
Properties:
-
Default timeout: 60 minutes
-
Maximum for standard jobs: 5760 minutes (4 days)
-
Maximum for custom jobs: 4320 minutes (3 days)
-
Job is cancelled if timeout is exceeded
| The total time allowed for a workflow run is 5760 minutes (4 days). All jobs and approvals must be completed within this time. |
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