Skip to content

Defining behaviour

Jump to bottom
Luis Medel edited this page Nov 11, 2024 · 2 revisions

Note to readers: This documentation is still in its early stages and may be (in fact, it is) incomplete.

Defining Behavior

Understanding the key concepts of Bluish is crucial for effectively defining the behavior of workflows, jobs, and steps. These concepts help you structure your automation efficiently and leverage Bluish's features to their fullest potential. For a comprehensive overview of these foundational elements, please refer to the Key Concepts Document.

In Bluish, the behavior of Jobs and Steps can be controlled and customized using a set of attributes. These attributes allow you to manage conditions, environment settings, output handling, and more. Some attributes are common across workflows, jobs, and steps, while others are specific to each scope.

Certain attributes are inheritable, meaning that if they are defined at a higher level (e.g., at the job level), they are automatically shared with all lower-level elements (e.g., steps within that job) unless explicitly overridden. Inheritable attributes simplify workflows by allowing configuration at a higher level to apply throughout, reducing repetition and ensuring consistency. If an attribute is inheritable, it will apply to all sub-elements unless a different value is specified at a lower level, which overrides the inherited value.

In the following tables, you will see which attributes are Optional and Inheritable, making it easier to understand how to leverage them effectively in your workflows.

Workflow Attributes

A workflow is the highest-level entity in Bluish, defining the overall automation process. Workflows contain multiple Jobs and provide attributes to control the overarching behavior.

Attribute Type Optional Inheritable Description
name string Yes No A descriptive name for the workflow.
jobs array of jobs No No The list of job definitions that make up the workflow.

Job Attributes

Jobs are composed of a series of Steps to perform a set of related tasks. Job-level attributes define the conditions and environment under which these steps are executed.

Attribute Type Optional Inheritable Description
name string Yes No A descriptive name for the job.
if expression Yes No Evaluates an expression to determine if the job should run. The expression must evaluate to true or any non-zero, non-empty value.
depends_on array of string Yes No A list of job IDs that this job depends on. The specified jobs will be executed before this job runs.
echo_commands boolean Yes Yes Specifies whether Bluish should echo the executed commands. Default is true.
echo_output boolean Yes Yes Specifies whether Bluish should echo the action's output. Default is true.
is_sensitive boolean Yes Yes Indicates that the job is sensitive, so Bluish will not echo the commands or outputs. This disables both echo_commands and echo_output. Default is false.
runs_on string Yes No Defines where the commands should run. Accepted values are docker://<image>, docker://<container id>, ssh://host, or empty for local execution. Note: When using ssh://[user@]host, only hosts that allow SSH key-based authentication are supported. Interactive user/password logins are not currently permitted.
steps array of steps No No The list of steps that make up the job.

About runs_on Values:

  • docker://<image>: Starts a new container using the specified image (e.g., ubuntu:latest). The container will be removed after the job completes.
  • docker://<container id>: Specifies an existing container by name or ID for executing the job.
  • ssh://[user@]host: Runs the commands on a remote host via SSH. Only SSH key-based authentication is supported.
  • Empty value: Commands are executed locally.

Step Attributes

Steps represent individual actions within a job and are the most granular unit of work in Bluish. Each step can be configured using the following attributes:

Attribute Type Optional Inheritable Description
id identifier Yes No The step identifier, used for referencing its outputs and results.
name string Yes No A descriptive name for the step.
if expression Yes No Evaluates an expression to determine if the step should run. The expression must evaluate to true or any non-zero, non-empty value.
echo_commands boolean Yes Yes Specifies whether Bluish should echo the commands executed in this step. Default is true.
uses string Yes No Specifies the action to be run in this step. See the action documentation for more information. Default is blank (uses the default action).
echo_output boolean Yes Yes Specifies whether Bluish should echo the command output. Default is true.
is_sensitive boolean Yes Yes Indicates that the step is sensitive, so Bluish will not echo the commands or outputs. Disables both echo_commands and echo_output. Default is false.
with dictionary Yes No A set of key-value pairs to provide as input values to this action. See the action-specific documentation for expected inputs.

Expression Evaluation and Expansion

Bluish allows attribute values to be dynamically evaluated through expressions, similar to GitHub Actions. These expressions enable calculations, conditionals, and variable expansions directly within your workflows. The syntax for these expressions uses ${{ ... }} to evaluate the contents.

Here are some examples demonstrating Bluish's expression capabilities:

Supported Operations

  • Mathematical Operations: You can perform arithmetic operations, such as addition, subtraction, multiplication, and division.

    # Adding 10 to a variable
run: |
  echo ${{ var.x + 10 }}

  • Comparison Operations: Expressions support comparisons (==, !=, <, >, <=, >=) for numerical or string values.

    # Check if a value is equal to 10
if: ${{ var.x == 10 }}

  • Logical Operations: Logical operators like &&, ||, and ! are available for combining conditions.

    # Combine conditions using logical AND
if: ${{ var.x > 5 && var.y < 20 }}

  • Boolean Evaluation: Values can be coerced to a boolean context to determine if they are true or false.

    # Use a value as a boolean condition
if: ${{ var.x }}

Expression Examples

Below are several examples of expressions evaluated within Bluish workflows:

  • Basic Arithmetic

    >>> ctx.set_value("var.x", 10)
>>> parse("${{ x + 10 }}")
20.0
>>> parse("${{ x * 10 }}")
100.0
>>> parse("${{ x == 10 }}")
True
>>> parse("${{ x != 10 }}")
False

  • Comparison Operators

    >>> parse("${{ x < 10 }}")
False
>>> parse("${{ x > 10 }}")
False
>>> parse("${{ x <= 10 }}")
True
>>> parse("${{ x >= 10 }}")
True

  • Logical Operators

    >>> parse("${{ x && true }}")
True
>>> parse("${{ x || false }}")
True
>>> parse("${{ !x }}")
False

  • Boolean Evaluation

    >>> bool(parse("${{ x }}"))
True
>>> bool(parse("${{ true }}"))
True
>>> bool(parse("${{ false }}"))
False

  • Variable Types and Expansion

    >>> ctx.set_value("var.x", 10)
>>> parse("${{ x }}")
10.0
>>> ctx.set_value("var.x", "hello")
>>> parse("${{ x }}")
'hello'
>>> ctx.set_value("var.x", True)
>>> parse("${{ x }}")
True

  • String Concatenation and Secrets

    >>> parse('${{ "a" + "b" }}')
'ab'
>>> parse('${{ "a" + secrets.password }}')
'a1234'
>>> parse('${{ secrets.password }}').redacted_value
'********'

These examples illustrate the versatility of Bluish's expression evaluation, allowing complex logic and dynamic value manipulations directly within your workflow configurations.

Clone this wiki locally