---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/workflows.md
  - href: en/sourcecraft/ci-cd-ref/workflows.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
title: Workflows
description: 'Description of SourceCraft CI/CD workflows: parameters, settings, environment variables, and configuration examples.'
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt


# Workflows

<!-- source: en/_includes/sourcecraft/ci-cd/workflows-description.md -->
The `workflows` section lists CI/CD _workflows_.

A workflow helps you organize [tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#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.

You can make a workflow [runnable by all organization members](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/public-workflows.md).
<!-- endsource: en/_includes/sourcecraft/ci-cd/workflows-description.md -->

Supported properties:
* `tasks`: List of [tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md) that are part of the workflow.
* `settings`: [Settings](#settings) valid for the entire workflow.
* `env`: [Environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#variables) available to all cubes within all tasks of a specific workflow. For more information, see [Example of a workflow with secrets and variables, including predefined ones](#workflow-with-vars).

  {% note tip %}

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

  {% endnote %}

* `runs_on`: [Tags of the worker](#runs-on) the workflow tasks will run on.
* `inputs`: [Parameters](#inputs) for manually starting a workflow or starting it on a schedule.
* `checkout`: [Settings](#checkout) for auto-cloning the repository prior to the workflow tasks.

## settings {#settings}

The `settings` section specifies the settings that are valid for the entire workflow:
* `max_cube_duration`: Maximum cube duration in seconds (`s`) or minutes (`m`). Default value: 5 minutes. Here is an example:

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

* `shared`: Permission to run the workflow for all [organization](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#org) members, including those holding no roles in the workflow repository. 

  For more information, see [Configuring a public workflow in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/public-workflows.md).

##### Example of configuring and running a public workflow {#example-public-workflow}

Configuration:

<!-- source: en/_includes/sourcecraft/ci-cd/public-workflow-config-example.md -->
```yaml
workflows:
  professor-test:
    inputs:
      STUDENTREPO:
        type: string
        required: true
      TASK:
        type: string
        required: true
    settings:
      shared: true
    tasks:
      - name: professor-task
        cubes:
          - name: professor-cube
            script:
              - |
              	mkdir -p artifacts
                echo "Repo: ${{ inputs.STUDENTREPO }}" > artifacts/professor-output
                echo "Task: ${{ inputs.TASK }}" >> artifacts/professor-output
            artifacts:
              paths:
                - artifacts/professor-output

on:
  push: professor-test
```
<!-- endsource: en/_includes/sourcecraft/ci-cd/public-workflow-config-example.md -->

Running a workflow by another member of the organization:

{% list tabs group=instructions %}

- CI/CD {#ci-cd}

  <!-- source: en/_includes/sourcecraft/ci-cd/public-workflow-run-example-ci.md -->
  ```yaml
  workflows:
    check-solution:
      tasks:
        - name: main
          cubes:
            - name: run-shared-workflow
              image: cr.yandex/sourcecraft/cubes/shared-workflows:latest
              env:
                ORG_SLUG: professor-org
                REPO_SLUG: professor-repo
                WORKFLOW_NAME: professor-test
                WORKFLOW_VALUES: '[{"name": "STUDENTREPO", "value": "student"}, {"name": "TASK", "value": "task-1"}]'
                TASK_NAME: professor-task
                CUBE_NAME: professor-cube
                ARTIFACT_LOCAL_PATH: artifacts/professor-output
              artifacts:
                paths:
                  - artifacts/output

  on:
    push: check-solution
  ```
  <!-- endsource: en/_includes/sourcecraft/ci-cd/public-workflow-run-example-ci.md -->

- API {#api}

  <!-- source: en/_includes/sourcecraft/ci-cd/public-workflow-run-example-api.md -->
  1. [Create](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md#create) a personal access token (PAT).
  1. Run the public workflow by providing `"shared": true` in the request body:

      ```bash
      export PAT=<personal_access_token>

      cat > body.json << 'EOF'
      {
        "workflows": [
          {
            "name": "professor-test",
            "values": [
              {
                "name": "STUDENTREPO",
                "value": "student"
              },
              {
                "name": "TASK",
                "value": "task-1"
              }
            ]
          }
        ],
        "shared": true
      }
      EOF

      curl \
        --request POST \
        --header "Authorization: Bearer $PAT" \
        --data '@body.json' \
        --url "https://api.sourcecraft.tech/<organization_slug>/<repository_slug>/cicd/runs"
      ```

      {% note warning %}

      You can only run a public workflow in the repository's main branch and only with the CI/CD configuration from the main branch. Providing `head` and `config_revision` in the request body will produce an execution error.

      {% endnote %}

      Save the execution `slug` value from the response.

  1. Get the status of a running workflow:

      ```bash
      curl \
        --request GET \
        --header "Authorization: Bearer $PAT" \
        --url "https://api.sourcecraft.tech/<organization_slug>/<repository_slug>/cicd/runs/<execution_slug>"
      ```

      {% note info %}

      The status and artifacts of a public workflow can only be accessed with the same [personal token (PAT)](https://sourcecraft.dev/portal/docs/en/sourcecraft/security/pat.md) used to run the workflow.

      {% endnote %}

  1. Get artifacts of a running workflow:

      ```bash
      curl \
        --request GET \
        --header "Authorization: Bearer $PAT" \
        --url "https://api.sourcecraft.tech/<organization_slug>/<repository_slug>/cicd/artifacts/<execution_slug>/professor-test/professor-task/professor-cube"
      ```

  For more information, see [Working with the SourceCraft REST API](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/api-start.md).
  <!-- endsource: en/_includes/sourcecraft/ci-cd/public-workflow-run-example-api.md -->

{% endlist %}

## 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 workflow with two tasks in different formats {#examples-two-tasks-diff-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](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md).

```yaml
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 {#examples-two-processes-diff-types}

```yaml
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 {#workflow-with-vars}

<!-- source: en/_includes/sourcecraft/ci-cd/config-with-vars.md -->
```yaml
# Defining global variables
# to provide to all cubes of all tasks in all workflows.
env:
  GLOBAL_VAR: global_var
  GLOBAL_SECRET: ${{ secrets.<secret_name> }}

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> }}
              # Reusing global variables, 
              # e.g., GLOBAL_VAR and GLOBAL_SECRET
              LOCAL_VAR: ${{ env.<global_variable_1> }}
              LOCAL_SECRET: ${{ env.<global_variable_2> }}
              # Reusing workflow variables,
              # e.g., WORKFLOW_VAR
              LOCAL_VAR2: ${{ env.<workflow_variable> }}

            script:
              - echo "$TASK_ENV_VAR"
              - echo "$MULTILINE_VAR"
              - echo "$CUBE_ENV_VAR"
              - echo "$SECRET_VAR"
              - echo "$WORKFLOW_VAR"
              - echo "$LOCAL_VAR"
              - echo "$LOCAL_VAR2"
              - echo "$LOCAL_SECRET"

          - 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"
              - echo "$GLOBAL_VAR"

      - name: my-task-2
        cubes:
          - name: my-cube-3
            script:
              - echo "$WORKFLOW_VAR"
              - echo "$GLOBAL_VAR"
```
<!-- endsource: en/_includes/sourcecraft/ci-cd/config-with-vars.md -->

## inputs {#inputs}

Under `inputs`, specify the parameters for manually starting the workflow or starting it on a schedule. 

In general, this section looks like this:

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

<!-- source: en/_includes/sourcecraft/ci-cd/input-configs.md -->
Where:
* `type`: Parameter type. The possible values are:
    * `string`: String.
    * `bool`: Logical value, `true` or `false`.
    * `choice`: Select from the preset values. 

    {% note info %}

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

    {% endnote %}

* `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.
<!-- endsource: en/_includes/sourcecraft/ci-cd/input-configs.md -->

<!-- source: en/_includes/sourcecraft/ci-cd/inputs-note.md -->
{% note tip %}

Navigate to ![image](../../_assets/console-icons/terminal-line.svg) **CI/CD** **→** ![image](../../_assets/console-icons/arrows-3-rotate-right.svg) **CI/CD** in your repository or an execution page to view parameter values for each manually executed [workflow](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#workflows).

This enables you to distinguish between workflows executed with different parameters.

{% cut "Example of how it looks in the interface" %}

![image](../../_assets/sourcecraft/manual-workflow-configs.png)

{% endcut %}

{% endnote %}
<!-- endsource: en/_includes/sourcecraft/ci-cd/inputs-note.md -->

Examples of using `inputs`:
* [Manual execution](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/run-workflow-manually.md#run-with-params)
* [Scheduled execution](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md#inputs-schedule)

## 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 level of an individual [task](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md#checkout). In this case, the task settings have priority over the workflow settings.

{% endnote %}

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

```yaml
workflows:
  my-workflow:
    checkout:
      retry: 2
      enabled: true
      remove_credentials: false
      fetch_depth: 10
```

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

* [Trigger events (on)](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md)
* [Tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.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)