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.

You can make a workflow runnable by all organization members.

Supported properties:

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. Example:

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

  • shared: Permission to run the workflow for all organization members, including those holding no roles in the workflow repository.

    For more information, see Configuring a public workflow in SourceCraft.

Example of configuring and running a public workflow

Configuration:

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

Running a workflow by another member of the organization:

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

  1. Create a personal access token (PAT).

  2. Run the public workflow by providing "shared": true in the request body:

    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"

    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.

    Save the execution slug value from the response.

  3. Get the status of a running workflow:

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

    Note

    The status and artifacts of a public workflow can only be accessed with the same personal token (PAT) used to run the workflow.

  4. Get artifacts of a running workflow:

    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.

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
# 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"

inputs

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

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.

Tip

Navigate to CI/CD → CI/CD in your repository or an execution page to view parameter values for each manually executed workflow.

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

Example of how it looks in the interface

image

Examples of using the inputs section:

See also

Previous
Trigger events (on)
Next
Tasks