Tasks

The tasks section defines a list of tasks that are part of the workflow.

Each task contains a series of minimum logical actions, i.e., cubes. The result of a task is when all its cubes are completed.

Note

All cubes within a single task are run on the same VM (worker). This way, if a cube changes the worker environment, such as installs a package, creates or deletes a file, etc., such environment will still be there for all other cubes running within a single task. For example, one cube may install the runtime package for Go, another one runs the go build command, and the next one runs go test. Learn more about environment inheritance in Cubes.

If the cubes are run in different tasks, they are guaranteed to run on different workers.

By default, a task starts with cloning the repository.

All workflow tasks are started concurrently.

In tasks and cubes, you can use environment variables and secrets.

You can set up a particular task either within the workflows:tasks section or in the separate tasks section with a link to it from workflows:tasks. The task description format for both options is the same.

Supported properties:

  • name: Task name.

  • cubes: List of cubes to execute as part of the task. For more information, see Cubes.

  • env: Environment variables available to all cubes within a certain task. For more information, see Example of a workflow with secrets and variables, including predefined ones.

    Tip

    You can also set environment variables within the following sections:

    • workflows: Variables will be available to all cubes within all tasks of a specific workflow.
    • cubes: Variables will be available in a specific cube.

  • uses: Parameter that allows reusing the cubes, name, env, and runs_on field values from another task in the current one. You can override the name, env, and runs_on values. You cannot override the cubes value. For more information, see Example of using dependencies and reusing task parameters.

    Warning

    You can use the uses parameter only within the workflows:tasks section. You cannot use it in the separate tasks section.

    The task whose parameters are reused may be located both inside the workflows:tasks section or in the separate tasks section.

  • needs: List of tasks to execute before the current one. The worker will get the task for execution only after all dependencies complete successfully. By default, each task has no dependencies and may be executed simultaneously with other workflow tasks. For more information, see Example of using dependencies and reusing task parameters.

    Warning

    You can use the needs parameter only within the workflows:tasks section. You cannot use it in the separate tasks section.

    In the needs field, you can only reference tasks of the workflow within which the current task is executed. Circular dependencies are not allowed.

  • runs_on: Tags of the worker the workflow tasks will run on. By default, it will use the value from workflow:runs_on.

  • checkout: Settings for auto-cloning the repository prior to the task. The settings from workflow:checkout apply by default.

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 task within the workflows:taskssection
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
    ...
Example of a task in the separate 'tasks' section
tasks:
  - name: common-task

workflows:
  my-workflow:
    tasks:
      - common-task
Example of several tasks in the separate 'tasks' section
tasks:
  - name: common-task-1
  - name: common-task-2

workflows:
  my-workflow:
    tasks:
      - [common-task-1, common-task-2]
Example of combined task specification
tasks:
  - name: common-task-1
  - name: common-task-2
  - name: common-task-3

workflows:
  my-workflow:
    tasks:
      - common-task-1
      - [common-task-2, common-task-3]
      - name: my-task
        cubes:
    ...
Example of using dependencies and reusing task parameters
tasks:
  # Source task whose parameters are reused in
  # other tasks.
  - name: sample-task
    env:
      HELLO: Hello
      WORLD: World
      SLEEP: 1
    cubes:
      - name: sample-cube
        script:
          - echo $HELLO, $WORLD
          - sleep $SLEEP

workflows:
  sample-workflow:
    tasks:
      # Link to the source task (tasks:sample-task).
      - sample-task
      - name: use1
        # For the use1 task, the parameters of the
        # source task (tasks:sample-task) are reused.
        uses: sample-task
        # The use1 task will be executed only after 
        # the following task is successfully completed:
        # sample-workflow:tasks:sample-task.
        needs: [sample-task]
        # Overriding variables from tasks:sample-task
        env:
          HELLO: Hallo
          WORLD: Welt
          SLEEP: 30
      - name: use2
        # For the use2 task, the parameters of the
        # original task (tasks:sample-task) are reused.
        uses: sample-task
        # The use2 task will be executed only after 
        # the following tasks are successfully completed:
        # sample-workflow:tasks:sample-task and 
        # sample-workflow:tasks:use1.
        needs: [use1, sample-task]
        # Overriding variables from tasks:sample-task
        env:
          HELLO: Hello
          WORLD: World
  another-workflow:
    tasks:
      # For this task, the parameters of the
      # source task (tasks:sample-task) are reused, including the name.
      - uses: sample-task

Note

The - sample-task and - uses: sample-task records are equivalent; however, you can use the second one to rename a task (name), define its new environment variables (env) or override the existing ones, as well as update worker labels (runs_on).

checkout

The checkout section contains auto-cloning settings for the repository you are running the workflow in. If you set this section both at workflow and task level, the task uses its own settings.

Supported properties:

  • enabled: Auto-cloning the repository prior to the task. The default value is true. If false, the repository will not be cloned before starting the task. In which case get the repository contents in one of the task cubes as needed.

    Note

    You can get the parameter value in the SOURCECRAFT_CHECKOUT_ENABLED predefined environment variable.

  • fetch_depth: Number of most recent history records to load when cloning the repository. It is not set by default; therefore, the repository is cloned down to its full history depth.

    Tip

    Use this parameter to accelerate uploading data to the task.

  • remove_credentials: Deletion of the authorization key from .git/config after cloning the repository. The default value is false. Set to true to prohibit further operations with the deleted repository from the task cubes under CI/CD authentication.

  • retry: Repository cloning auto-retry settings. This parameter is set in one of the following formats:

    Unlike the cube’s retry parameter, this setting affects only the repository cloning retry. Auto-retry of repository cloning is disabled by default.

Note

You can also set the checkout settings at the workflow level. If you set this section both at workflow and task level, the task uses its own settings.

Example of configuring repository cloning at the task level
tasks:
  - name: ci-build
    checkout:
      retry: 2
      enabled: true
      remove_credentials: false
      fetch_depth: 10

Useful links

Previous
Workflows
Next
Cubes