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. Here is an 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, specify the parameters for manually starting a workflow. 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.

For an example of using inputs, see Starting a workflow manually with custom parameters.

See also

Previous
Trigger events (on)
Next
Tasks