`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 the `env` usage example.
`steps`	Contains information about steps run in the current job. Refer to the `steps` usage example.
`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.
`needs`	Contains outputs of jobs required for the current job to execute.
`inputs`	Use the `inputs` context for input properties (of type `string`, `number`, or `boolean`) that are passed to an action or a manually triggered workflow. For manually triggered workflows, the inputs are defined in the `workflow_dispatch` event configuration of a workflow.

`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.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.registries`	String	The path to the registry mirror configuration file.
`cloudbees.run_attempt`	Number	Every run for a workflow in a component has a unique `run_attempt` number per `run_id` , which provides an immutable reference to that run.
`cloudbees.run_id`	String	Every workflow in a repository has a unique ID number, the `run_id`, that does not change.
`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.

`env` context usage

Use the env context to define environment variables for containers that are specified in a step. These variables can be used at three different scope levels:

Workflow
Job
Step

The values for the variables on the job and step levels can be set as strings or referenced from job outputs.

For example, the env keyword is used for the context of a job:

env:
  VERSION: latest▼

`steps` context usage

Use the steps context to set an output value from a step in the job’s outputs. It can then be referenced in a separate job using the needs context.

For example:

      generate-greeting:
        outputs:
          greeting: ${{ steps.greet.outputs.greeting }}
        steps:
        - id: greet
          uses: docker://alpine:3.20
          run: |
            echo "hello world" > $EXAMPLE_OUTPUTS/greeting
      print-greeting:
        needs:
        - generate-greeting
        steps:
        - name: print
          uses: docker://alpine:3.20
          run: |
            echo ${{ needs.generate-greeting.outputs.greeting }}▼

`cloudbees` and other context objects

cloudbees context

env context usage

steps context usage

`cloudbees` context

`env` context usage

`steps` context usage