---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/tasks.md
  - href: en/sourcecraft/ci-cd-ref/tasks.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt

# Tasks

<!-- source: en/_includes/sourcecraft/ci-cd/tasks-description.md -->
The `tasks` section defines a list of tasks that are part of the [workflow](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#workflows).

Each task contains a series of minimum logical actions, i.e., [cubes](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#cubes). The result of a task is when all its cubes are completed.

{% note info %}

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](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md).

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

{% endnote %}

By default, a task starts with cloning the repository.

All workflow tasks are started concurrently.

In tasks and cubes, you can use [environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#variables) and [secrets](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#secrets).
<!-- endsource: en/_includes/sourcecraft/ci-cd/tasks-description.md -->

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](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md).
* `env`: [Environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#variables) available to all cubes within a certain task. For more information, see [Example of a workflow with secrets and variables, including predefined ones](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md#workflow-with-vars).

  {% note tip %}

  You can also set environment variables within the following sections:
  * [workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md): Variables will be available to all cubes within all tasks of a specific workflow.
  * [cubes](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md): Variables will be available in a specific cube.

  {% endnote %}

* `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](#tasks-uses-needs).

  {% note 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.

  {% endnote %}

* `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](#tasks-uses-needs).

  {% note 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.

  {% endnote %}

* `runs_on`: [Tags of the worker](#runs-on) the workflow tasks will run on. By default, it will use the value from `workflow:runs_on`.
* `checkout`: [Settings](#checkout) for auto-cloning the repository prior to the task. The settings from `workflow:checkout` apply by default.

## runs_on {#runs-on}

<!-- source: en/_includes/sourcecraft/ci-cd/runs-on.md -->
The `runs_on` field gives a list of [worker](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md) tags on which the workflow tasks will run. Supported tag types:
* Runtime tag: Worker type. The possible values are:
  * `compute`: [Cloud worker](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md#cloud-workers). This is a default value.
  * `serverless`: [Serverless worker](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md#serverless-workers). See examples [here](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md#serverless-workflow-example).
  * `self-hosted`: [Self-hosted worker](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md#self-hosted-workers).

  {% note warning %}

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

  {% endnote %}

* [Self-hosted worker tags](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/self-hosted-tags.md).

  <!-- source: en/_includes/sourcecraft/ci-cd/self-hosted-tag-note.md -->
  {% note info %}

  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`.

  {% endnote %}
  <!-- endsource: en/_includes/sourcecraft/ci-cd/self-hosted-tag-note.md -->
<!-- endsource: en/_includes/sourcecraft/ci-cd/runs-on.md -->

##### Example of a task within the `workflows:tasks` section {#task-inside}

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
    ...
```

##### Example of a task in the separate 'tasks' section {#task-out}

```yaml
tasks:
  - name: common-task

workflows:
  my-workflow:
    tasks:
      - common-task
```

##### Example of several tasks in the separate 'tasks' section {#many-tasks-out}

```yaml
tasks:
  - name: common-task-1
  - name: common-task-2

workflows:
  my-workflow:
    tasks:
      - [common-task-1, common-task-2]
```

##### Example of combined task specification {#many-tasks-combined}

```yaml
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-uses-needs}

```yaml
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 info %}

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`).

{% endnote %}

## checkout {#checkout}

<!-- source: en/_includes/sourcecraft/ci-cd/checkout.md -->
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 info %}

  You can get the parameter value in the `SOURCECRAFT_CHECKOUT_ENABLED` [predefined environment variable](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/predefined-variables.md).

  {% endnote %}

* `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.

  {% note tip %}

  Use this parameter to accelerate uploading data to the task.

  {% endnote %}

* `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:

  * Number: Maximum number of cloning retries. For more information, see [Restart by default](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md#retry-default).
  * Retry condition structure. For more information, see [Restart with conditions](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md#retry-conditions).

  Unlike the cube’s `retry` parameter, this setting affects only the repository cloning retry. Auto-retry of repository cloning is disabled by default.
<!-- endsource: en/_includes/sourcecraft/ci-cd/checkout.md -->

{% note info %}

You can also set the `checkout` settings at the [workflow](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md#checkout) level. If you set this section both at workflow and task level, the task uses its own settings.

{% endnote %}

##### Example of configuring repository cloning at the task level {#tasks-checkout-example}

```yaml
tasks:
  - name: ci-build
    checkout:
      retry: 2
      enabled: true
      remove_credentials: false
      fetch_depth: 10
```

#### Useful links {#see-also}

* [Cubes](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md)
* [Trigger events (on)](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md)
* [Workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md)
* [Continuous integration and continuous deployment in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md)
* [Configuring CI/CD in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/ci-cd.md)
* [Managing secrets in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/secrets.md)
* [Processing environment variables in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/variables.md)