Use cloudbees and other context objects

Understanding context information in the CloudBees platform is key to a successful workflow.

Access contexts using an expression that references a context. You can use the if keyword for conditional expressions.

The following table lists the platform context objects and their scopes.

Table 1. Context objects and their scopes
Context object name	Description
`cloudbees`	Information about the workflow run. Refer to the `cloudbees` context table for more information.
`env`	Contains variables set in a workflow, job, or step for outputs. Refer to env
`file`	Use the expression `${{ file.scm.sha }}` to represent the Git commit SHA of the file in which it appears. Enables commit-specific tagging of container images to avoid conflicts and reduce manual updates. Used in: `uses:` field in workflow steps `image:` field in job services Refer to: Using `file.scm.sha` Expression for more information.
`inputs`	Use the `inputs` context to add input parameters. Valid parameter types: `string`, `number`, `boolean` and `choice`.
`needs`	Contains outputs of jobs required for the current job to execute.
`outputs`	Use the `outputs` context to extract parameter `input` values in JSON format. For example, to return: All parameter input values provided by a workflow approver in JSON format use: `needs` syntax of `${{needs.<approval_job_name>.outputs.approvalInputValues).<parameter_name>}}`. A specific approval parameter input value use: `${{ fromJSON(needs.<approval_job_name>.outputs.approvalInputValues).<parameter_name>}}`.
`steps`	Contains information about steps run in the current job. Refer to jobs.<job_id>.steps.
`secrets`	Use the `secrets` and `vars` contexts to reference properties that are specified on the platform (component-specific and inherited properties). Use `secrets` for sensitive information, and `vars` for everything else. Their only difference is that all output or logs that reference `secrets` is redacted.

`cloudbees` context

The cloudbees context contains workflow run information.

Table 2. `cloudbees` context objects and their scopes
Property name	Data type	Description
`cloudbees`	Object	The top-level context.
`cloudbees.api`	String	The REST API name.
`cloudbees.api.token`	String	A token for authenticating to the CloudBees APIs.
`cloudbees.api.url`	String	The REST API URL.
`cloudbees.component.id`	String	The CloudBees platform identifier for a component.
`cloudbees.event`	Object	The webhook payload that triggers a workflow run. `workflow_dispatch` contains the inputs and `schedule` contains the cron definition. `push` and `pull_request` contain the raw SCM payload.
`cloudbees.event_name`	String	The name of the event that triggers a workflow run: `push`, `pull_request`, `workflow_dispatch`, or `schedule`.
`cloudbees.home`	String	The home directory inside the current container; defaults to `/cloudbees/home`.
`cloudbees.org.id`	String	The CloudBees platform identifier for the organization.
`cloudbees.registries`	String	The path to the registry mirror configuration file.
`cloudbees.run_attempt`	Number	A unique number representing each attempt of a specific workflow run. Each run_id may have multiple retry attempts, and this value distinguishes between them while remaining fixed for each individual attempt.
`cloudbees.run_id`	String	A globally unique identifier assigned to each execution of a workflow. This identifier remains constant for the duration of the run.
`cloudbees.run_number`	Number	A unique, incrementing value assigned to each workflow run within a component. This value reflects the run sequence for a specific workflow, independent of branches or pull request variations.
`cloudbees.scm`	Object	The parent context for the SCM keys.
`cloudbees.scm.branch`	String	The name of the repository branch that contains the workflow file.
`cloudbees.scm.provider`	String	The SCM provider. Valid values are `github`, `bitbucket`, and `bitbucket_datacenter`.
`cloudbees.scm.provider_url`	String	The SCM provider host URL; for example, `https://github.com`.
`cloudbees.scm.ref`	String	The branch or tag ref that triggers a workflow run. For example, a branch or tag ref that is pushed in a workflow with a `push` trigger, or the pull request merge branch ref in a workflow with a `pull_request` trigger.
`cloudbees.scm.repository`	String	The repository path in the format `<OWNER_NAME>/<REPOSITORY_NAME>`.
`cloudbees.scm.repositoryUrl`	String	The URL of the SCM repository.
`cloudbees.scm.sha`	String	The commit SHA for the workflow file.
`cloudbees.scm.token`	String	This value should normally be left to pick up the default value of ${{ cloudbees.scm.token }}, which injects the CloudBees workflow run token that uniquely identifies a job run within a workflow, and is used to authenticate that run against CloudBees services.
`cloudbees.workspace`	String	The default working directory for platform workflows.
`cloudbees.version`	String	This is a CloudBees-maintained version of a component. For workflow trigger events, the patch number is incremented.

If you do not explicitly specify an SCM personal access token with the necessary permissions when invoking the Check out a Git repository action, the action uses the cloudbees.api.token input to make a call back to the CloudBees platform to request an SCM token (cloudbees.scm.token) with the necessary permissions.

Using `file.scm.sha` Expression

Use ${{ file.scm.sha }} to reference commit-specific container images within workflows and actions. This approach helps ensure consistency between referenced images, avoids tag conflicts, and eliminates the need for manual updates.

Limitations

Only the file.scm.sha expression is allowed in these fields; full dynamic expressions or outputs from other jobs are not supported.
Docker image tag values must comply with naming rules:
- Valid ASCII characters only
- May include letters, digits, underscores (_), periods (.), and dashes (-)
- Must not begin with a period or dash
- Maximum length: 128 characters

Benefits

Enables actions and images defined in the same repository to coordinate builds without manual tag updates.
Supports workflows that build an image in one job and safely consume it in another job within the same workflow.
Prevents conflicts between concurrent builds across branches or pull requests.

Example Usage

jobs:
  build:
    steps:
      - name: Checkout source
        uses: cloudbees-io/checkout

      - name: Build container image
        uses: cloudbees-io/kaniko
        with:
          destination: example.com/foo:latest-${{ file.scm.sha }}
          (1)
          dockerfile: ./Dockerfile
          context: .

  test:
    needs:
      - build
    services:
      self:
        image: example.com/foo:latest-${{ file.scm.sha }}
        (2)

    steps:
      - name: Run tests
        run: |
          curl http://self:8080/health▼

1	Uses `${{ file.scm.sha }}` to tag the container image with the commit SHA of the workflow file.
2	Refers to the same commit-tagged image to ensure consistency with the build job.