Workflows

The workflows section lists CI/CD workflows.

A workflow helps you organize tasks related to a certain CI/CD stage into a logical sequence.

For example, a single workflow may run for builds, tests, linting, code coverage verification, etc. All these steps will be different tasks as part of such a workflow. Then, you may have another workflow to generate documentation and deploy the new version to production.

All workflows are run concurrently.

Supported properties:

settings

The settings section specifies the settings that are valid for the entire workflow, for example:

workflows:
  my-workflow:
    settings:
      max_cube_duration: 20s

Where max_cube_duration is the maximum cube duration in seconds (s) or minutes (m). Default value: 5 minutes.

runs_on

The runs_on field gives a list of worker tags on which the workflow tasks will run. Supported tag types:

  • Runtime tag: Worker type. The possible values are:

    Warning

    The runs_on field cannot contain more than one runtime tag. If no runtime tag is specified, compute is used by default.

  • Self-hosted worker tags.

    Note

    A tag's string values ​can contain a limited range of characters: Latin letters (a-zA-Z), -, ., and _.

    For a self-hosted worker, parameters automatically include the self-hosted tag. You need not additionally add it to the tags field in config.yaml.

Example of a workflow with two tasks in different formats

One workflow task is within the workflows section, the other is outside it. my-task is an example of using cube dependencies; for more info, see Cubes.

tasks:
  - name: another-task
    cubes:
      - name: D
        script:
          - echo It's another task.

workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: A
            script:
              - touch test.txt
          - name: B
            needs: ['-']
            script:
              - rm -f test.txt
          - name: C
            needs: ['A', 'B']
            script:
              - ls
  
      - another-task
...
Example of two different workflows run depending on the event type
on:
  pull_request:
    - workflows: workflow-for-pr
      filter:
        source_branches: ["**", "!test**"]
        target_branches: "main"

  push:
    - workflows: workflow-for-push
      filter:
        branches: ["main"]

workflows:
  workflow-for-pr:
    tasks:
      - name: sample-task-1
        cubes:
          - name: sample-cube1
            image: docker.io/library/node
            script:
              - echo Hello, world!

  workflow-for-push:
    tasks:
      - name: sample-task-2
        cubes:
          - name: sample-cube2
            script:
              - echo Test, and deploy your project.
Example of a workflow with secrets and variables, including predefined ones
workflows:
  my-workflow:
    # Here you define variables that will be available in all cubes 
    # of all my-workflow tasks
    env:
      WORKFLOW_VAR: workflow-var
    
    tasks:
      - name: my-task
        # Here you define variables that will be available in all cubes 
        # within my-task
        env:
          TASK_ENV_VAR: This variable is available in all cubes of this task.
          # Multi-line variable
          MULTILINE_VAR: |
            multi-var
            multi-var
            this is my multi-var
        
        cubes:
          - name: my-cube-1
            # Here you define variables that will only be available
            # within my-cube-1
            env:
              CUBE_ENV_VAR: This variable is available only in cube my-cube-1.
              # Variable with a value from a secret
              SECRET_VAR: ${{ secrets.<secret_name> }}
            script:
              - echo "$TASK_ENV_VAR"
              - echo "$MULTILINE_VAR"
              - echo "$CUBE_ENV_VAR"
              - echo "$SECRET_VAR"
              - echo "$WORKFLOW_VAR"

          - name: my-cube-2
            # Here you define variables that will only be available 
            # within my-cube-2
            env:
              CUBE_ENV_VAR: This variable is available only in cube my-cube-2.
            script:
              - echo "$TASK_ENV_VAR"
              - echo "$CUBE_ENV_VAR"
              # Using a predefined variable
              - echo "$SOURCECRAFT_TASK"
              - echo "$WORKFLOW_VAR"

      - name: my-task-2
        cubes:
          - name: my-cube-3
            script:
              - echo "$WORKFLOW_VAR"

inputs

Under inputs, specify the parameters for manually starting a workflow. In general, this section looks like this:

inputs:
  <parameter_name>:
    type: <parameter_type>
    required: <whether_parameter_is_required>
    description: <parameter_description>
    default: <default_value>
    options: <possible_options_for_choice_type>

Where:

  • type: Parameter type. The possible values are:

    • string: String.
    • bool: Logical value, true or false.
    • choice: Select from the preset values.

    Note

    If the configuration contains the options parameter, you do not need to set the type: choice parameter.

    If the type is not specified and there is no options parameter, the default parameter type is string.

  • required: Required parameter. The possible values are true or false.

  • description: Any description of the parameter that will be displayed in the SourceCraft interface when manually running the workflow.

  • default: Default parameter value. You can also specify it if the parameter is required.

  • options: Possible values ​​for the choice parameter type.

For an example of using inputs, see Starting a workflow manually with custom parameters.

See also

Previous
Trigger events (on)
Next
Tasks