Variables and Values use in CircleCI

Using variables with Orbs can sometimes be confusing due to the scope limits of different kinds of variables. The variables and their scope discussed in this article include:

• Environment Variables

  • Environment variables are scoped at the job level, so they can be used with the context key in a job, but they do not exist at a pipeline level.

• Pipeline Values
  • Pipeline values, the pipeline-wide values that are provided by CircleCI
    (e.g. << pipeline.number >>) are always in scope.
• Pipeline Parameters 
  • Pipeline parameters can only be resolved in the .circleci/config.yml file in which they are declared. Pipeline parameters are not available in orbs, including orbs declared locally in your .circleci/config.yml file. This is because access to pipeline scope in orbs would break encapsulation and create a hard dependency between the orb and the calling configuration. This would potentially create a surface area of vulnerability, increasing security risks. 
  • Pipeline parameters that are defined in the configuration are always in scope, with two exceptions:

    • Pipeline parameters are not in scope for the definition of other pipeline parameters, so they cannot depend on one another.

    • Pipeline parameters are not in scope in the body of orbs, even inline orbs, to prevent data leaks.

• Element Parameters
  • Element parameters use lexical scoping, so parameters are in scope within the element they are defined in, for example, a job, a command, or an executor. If an element with parameters calls another element with parameters, the inner element does not inherit the scope of the calling element.

Understanding configuration processing

Along with understanding the variables, the order of config process has to be taken into account when using these parameters, especially with orbs. Configuration processing happens in the following stages:

Using variables with Orbs

When using pipeline parameters with is important to remember:

• Pipeline parameters are not in scope in the body of orbs, even inline orbs, to prevent data leaks.

This means that it is not possible to using a pipeline parameter when creating an orb and they must be passed in via the job config. An example of passing a variable to an orb can be seen below:

    steps:   
      - myorb/myjob:
          orb_param: <<pipeline.git.branch>>