Reusing workflow and cube parameters in SourceCraft CI/CD

In SourceCraft CI/CD, you can describe shared parameters of workflows and cubes once and then reuse them via the uses parameter. This reduces repetitions of configuration fragments and simplifies configuration maintenance: it is enough to update the shared sequence of actions in one place.

For example, to deploy several services, you can specify a shared workflow and provide to it the name of the service of interest. You can connect cubes from the current configuration file, other files, and repositories.

Workflows

If multiple workflows perform the same sequence of tasks, define the sequence once and reuse it with different input parameters. Follow these steps:

  1. In .sourcecraft/ci.yaml, define the workflow you want to reuse under workflows. Declare its input parameters in the inputs section and use their values in the configuration.
  2. In the caller workflow, specify the name of the reusable workflow in the uses parameter.
  3. Specify the values of its input parameters in the with section. The keys in this section must match the parameter names in the reusable workflow's inputs, and the values, their types and constraints.

Note

The caller workflow can have its own inputs section. The names and settings of input parameters pertaining to the caller and reusable workflows may differ. Map the parameters in the with section.

Example of reusing workflow parameters

In the example below, release-workflow contains the common sequence for building, testing, and deploying the application. Workflows for individual services reuse this sequence and provide the service name using the RELEASE_APP parameter.

We assume that the repository contains the build.sh, check.sh, and deploy.sh scripts that accept the service name as an argument:

workflows:
  release-workflow:
    inputs:
      RELEASE_APP:
        type: choice
        required: true
        options:
          - service1
          - service2
          - service3
    env:
      RELEASE_APP: ${{ inputs.RELEASE_APP }}
    tasks:
      - name: build-app
        cubes:
          - name: build
            script:
              - ./build.sh "$RELEASE_APP"

      - name: run-compliance-checks
        needs: [build-app]
        cubes:
          - name: check
            script:
              - ./check.sh "$RELEASE_APP"

      - name: deploy-app
        needs: [build-app, run-compliance-checks]
        cubes:
          - name: deploy
            script:
              - ./deploy.sh "$RELEASE_APP"

  service1-release-workflow:
    uses: release-workflow
    with:
      RELEASE_APP: service1

  service2-release-workflow:
    uses: release-workflow
    with:
      RELEASE_APP: service2

  service3-release-workflow:
    uses: release-workflow
    with:
      RELEASE_APP: service3

  manual-release-workflow:
    inputs:
      TARGET_APP:
        type: choice
        required: true
        default: service3
        options:
          - service1
          - service2
          - service3
    uses: release-workflow
    with:
      RELEASE_APP: ${{ inputs.TARGET_APP }}

For manual-release-workflow, the service name is set in the TARGET_APP parameter. The ${{ inputs.TARGET_APP }} expression in the with section provides its value to the RELEASE_APP parameter of the reusable workflow. This allows the caller and reusable workflows to use different input parameter names.

Cubes

You can use the uses parameter in the current cube to reuse the parameters of another cube. The syntax depends on the location of the cube to reuse:

You can redefine some of the current cube’s parameters. For more information, see Example of reusing cube parameters within a single .sourcecraft/ci.yaml file.

Example of reusing cube parameters within a single .sourcecraft/ci.yaml file
cubes:
  - name: external-cube
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR

tasks:
  - name: first-task
    cubes:
      - name: first-cube
        uses: external-cube
      # Reusing a cube with a redefined parameter
      - name: second-cube
        env:
          CUBE_VAR: world
        uses: external-cube

workflows:
  first-workflow:
    tasks:
      - first-task
Example of reusing cube parameters from a YAML file in the same repository

The .ci-files/cubes/bash-lib.yaml file containing the cube to reuse:

cubes:
  - name: external-cube-1
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR
  - name: external-cube-2
    script:
      - echo "world"

.sourcecraft/ci.yaml:

tasks:
  - name: first-task
    cubes:
      - name: first-cube
        uses: ./.ci-files/cubes/bash-lib.yaml/cubes/external-cube-1

workflows:
  first-workflow:
    tasks:
      - first-task
      - name: second-task
        cubes:
          - name: second-cube
            uses: ./.ci-files/cubes/bash-lib.yaml/cubes/external-cube-2
Example of reusing cube parameters from a YAML file in another repository

The .ci-files/cubes/bash-lib.yaml file with the cube to reuse, stored in the myrepo repository of the myorg organization:

cubes:
  - name: external-cube-1
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR
    # Flag that enables using the cube in other repositories
    exported: true
  - name: external-cube-2
    script:
      - echo "world"
    exported: true

The repository’s .sourcecraft/ci.yaml file containing the CI configuration:

tasks:
  - name: first-task
    cubes:
      - name: first-cube
        uses: myorg/myrepo/.ci-files/cubes/bash-lib.yaml/cubes/external-cube-1

workflows:
  first-workflow:
    tasks:
      - first-task
      - name: second-task
        cubes:
          - name: second-cube
            uses: myorg/myrepo/.ci-files/cubes/bash-lib.yaml/cubes/external-cube-2

Useful links

Previous
Cubes
Next
Service connections (tokens)