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 common parameters are described in the same way for both options, whereas uses and approval can only be used inside workflows:tasks.

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.

  • 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 Examples of using dependencies.

    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.

  • approval: Settings for manual approval of task execution. You can only use this parameter in tasks inside the workflows:tasks section.

  • outputs: Task output values that can be provided to dependent tasks. The values are set using expressions that reference the output values of cubes or tasks. For more information, see Providing data between CI/CD tasks in SourceCraft.

  • 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:
    ...
Examples of using dependencies
tasks:
  # Task that runs without dependencies.
  - name: sample-task
    cubes:
      - name: sample-cube
        script:
          - echo "Hello, World"
          - sleep 1

workflows:
  sample-workflow:
    tasks:
      # Link to the source task (tasks:sample-task).
      - sample-task
      - name: another-task
        # `another-task` will only be executed after
        # `sample-task` is successfully completed.
        needs: [sample-task]
        script:
          - echo "Here we go again"
          - sleep 1
      - name: yet-another-task
        # `yet-another-task` will only be executed after
        # `sample-task` and `another-task` are successfully completed.
        needs: [sample-task, another-task]
        script:
          - echo "Goodbye, World"
          - sleep 1

approval

With manual approval enabled, after you start a CI/CD pipeline, a task is Created and placed in a wait queue. The task remains in this status while the dependencies defined in the needs parameter are running. After all dependencies complete successfully, or if no dependencies are defined, the task status changes to AwaitingApproval, and the countdown for the approval timeout starts.

Possible outcomes:

  • Approval (approve): The task moves to the execution queue and starts normally. The system logs the outcome (approved), user details, and comment in the decision details.
  • Rejection (reject): The task is Rejected removed from the wait queue. The system logs the outcome (rejected), user details, and comment in the decision details. The Rejected status applies to the entire workflow and CI/CD execution.
  • Timeout expired (expire): If no decision is made in time, the task is Canceled, and the system logs the outcome (expired) in the decision details. The Canceled status applies to the entire workflow and CI/CD execution.

Note

When using manual approval, keep these restrictions in mind:

  • You can only approve or reject a task once. A repeated attempt will fail with the ALREADY_DECIDED result.
  • If require_comment: true, any attempt to submit a decision without a comment is rejected with the COMMENT_REQUIRED message.
  • If a CI/CD execution is canceled, a task in the AwaitingApproval status also gets Canceled.
  • If any of the task dependencies fail, the task status changes to Canceled, and the task is removed from the wait queue.

A task requiring manual approval does not run automatically when its dependencies complete successfully. It waits for the user to approve or reject the execution. This allows you, e.g., to verify the result before deploying it to the production environment.

Warning

Only repository users with the Repository developer role or higher can approve or reject tasks in the SourceCraft interface.

Warning

The approval parameter gives settings for manual approval of task execution inside the workflows:tasks section. It cannot be used in upper-level tasks described in a separate tasks section outside of workflows.

The following record forms are supported:

  • approval: true: Enable manual approval with the default timeout of 24 hours.
  • approval: false: Explicitly disable manual approval. This is equivalent to having no approval parameter.
  • approval: {}: Enable manual approval with default parameters.
  • approval: { timeout: ..., note: ..., require_comment: ... }: Enable manual approval with explicitly set parameters.

The approval section supports the following parameters. All parameters are optional:

  • timeout: Maximum decision timeout, e.g., 1h or 2h. The default value is 24h. The time starts the moment the task status changes to AwaitingApproval. As soon as the time ends, the task gets automatically canceled.
  • note: Instruction for the user who makes the decision. It is a string of under 1,000 characters displayed in the UI. Not set by default.
  • require_comment: Requirement to add a comment when the task is approved or rejected. Specified as a Boolean value. The default value is false. If set to true, the user can make a decision only with a comment. The maximum comment length is 2,000 characters regardless of the require_comment value.

For a step-by-step guide, see this guide.

Example of manual approval with the default timeout
workflows:
  release:
    tasks:
      - name: publish
        approval: true
        cubes:
          - name: publish-cube
            script:
              - echo "publish"
Example of a task with a dependency and manual approval
workflows:
  deploy:
    tasks:
      - name: build
        cubes:
          - name: build-cube
            script:
              - echo "build"
      - name: deploy
        needs: [build]
        approval:
          timeout: 1h
        cubes:
          - name: deploy-cube
            script:
              - echo "deploy"
Example of manual approval with a required comment and instructions
workflows:
  deploy:
    tasks:
      - name: build
        cubes:
          - name: build-cube
            script:
              - echo "build"
      - name: deploy-prod
        needs: [build]
        approval:
          timeout: 2h
          note: "Check the test environment dashboards"
          require_comment: true
        cubes:
          - name: deploy-cube
            script:
              - echo "deploy"

In this example, after the build task completes successfully, the deploy-prod task will wait for the user's decision for up to two hours. The user must provide a comment to approve or reject the execution. The echo commands illustrate the task execution order; replace them with the build and deployment commands for your application.

Example of explicitly disabling manual approval
workflows:
  deploy:
    tasks:
      - name: deploy-forced
        approval: false
        cubes:
          - name: deploy-cube
            script:
              - echo "deploy"

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 the workflow and task levels, 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