Configure Picasso Workflow#

Picasso is a Github Workflow implemented to be flexible enough to be adopted by different organizations with their own requirements. This document will guide you through the different configurations available to you when using the Picasso workflow in your repository.

Inputs#

Inputs are the parameters that you can set to customize the behavior of the Picasso workflow. The following inputs are available:

  • STRAIN_REPOSITORY (required): The URL of the repository that contains the strain configuration. This repository should contain a valid config.yml file that defines the strains that will be built.

  • STRAIN_REPOSITORY_BRANCH (required): The branch of the STRAIN_REPOSITORY to clone the strain configuration from. This branch should contain the version of the configuration file used to build the image.

  • STRAIN_PATH (required): The path to the directory that contains the strain configuration file. This path should be relative to the root of the repository.

  • SERVICE (required): The name of the service that will be built. This service should be supported by Tutor or by a tutor plugin previously installed.

  • ENABLE_LIMIT_BUILDKIT_PARALLELISM (optional): If set to true, the build process parallel steps will be limited by 3, which is the threshold found where both Open edX and MFE images are built without running out of resources in the Github Actions runner (please, see PR #12 for more details) . If set to false, the buildkit configuration default will be used. Default is true. Set to false if you have a runner with more resources.

  • RUNNER_WORKFLOW_LABEL (optional): This label should match the label of the runner that will execute the workflow. By default, the workflow will use one of the Github Actions standard runners, e.g., ubuntu-24.04.

  • PYTHON_VERSION (optional): The Python version to use in the workflow. By default, the workflow will use Python 3.12.

  • PICASSO_VERSION (optional): Picasso version to use for the workflow scripts and utility functions. This should be a valid branch, tag or commit and it should match the version of the workflow used. By default, the workflow will use the latest release major version, e.g., v1.

These inputs can be set in the workflow file that calls the Picasso workflow using the with keyword, by manually setting them in the workflow file, or by using the workflow_dispatch event. For more details on how to set input values in Github Actions, please refer to the Workflow syntax for GitHub Actions documentation.

Here is an example of how to use the Picasso workflow with the inputs set:

jobs:
    build:
        name: Build with Picasso
        uses: eduNEXT/picasso/.github/workflows/build.yml@main
        with:
            STRAIN_REPOSITORY: edunext/build-manifests
            STRAIN_REPOSITORY_BRANCH: dev/test-latest-image
            STRAIN_PATH: redwood/base
            SERVICE: mfe
            ENABLE_LIMIT_BUILDKIT_PARALLELISM: false
            RUNNER_WORKFLOW_LABEL: ubuntu-latest
            PYTHON_VERSION: 3.10
            PICASSO_VERSION: main

Secrets#

Secrets are the sensitive data that you can set to customize the behavior of the Picasso workflow. The following secrets are available:

  • SSH_PRIVATE_KEY (required): The private SSH key that will be used to clone private repositories, including the STRAIN_REPOSITORY and all private requirements for the Open edX images. Therefore, this key should have read access to all the repositories that are required to build the images.

  • DOCKERHUB_USERNAME (optional): The username of the Docker Hub account where the images will be pushed. By default, the images are pushed to a docker.io registry using this username.

  • DOCKERHUB_PASSWORD (optional): The password of the Docker Hub account where the images will be pushed. This password is used to authenticate the Docker client when pushing the images.

  • AWS_ACCESS_KEY_ID (optional): The access key ID of the AWS account where the images will be pushed. This key is used to authenticate the AWS client when pushing the images to the ECR registry.

  • AWS_SECRET_ACCESS_KEY (optional): The secret access key of the AWS account where the images will be pushed. This key is used to authenticate the AWS client when pushing the images to the ECR registry.

  • AWS_REGION (optional): The region of the AWS account where the images will be pushed. This region is used to determine the ECR registry URL where the images will be pushed.

These variables are mainly used to authenticate with some services like Docker Hub, AWS or GitHub. They should be set in the Github Actions repository’s secrets settings. For more information on how to set secrets in Github, please refer to the Using secrets in GitHub Actions documentation.

To correctly use Docker Hub or AWS registries to push images, you should set the corresponding configuration in your config.yml file. For more information on how to configure the Docker Hub or AWS registries in the config.yml file, please refer to the Configuring Docker Registries documentation.

Here is an example of how to use the Picasso workflow with the inputs and secrets set:

jobs:
    build:
        name: Build with Picasso
        uses: eduNEXT/picasso/.github/workflows/build.yml@main
        with:
            STRAIN_REPOSITORY: edunext/build-manifests
            STRAIN_REPOSITORY_BRANCH: dev/test-latest-image
            STRAIN_PATH: redwood/base
            SERVICE: mfe
            ENABLE_LIMIT_BUILDKIT_PARALLELISM: false
        secrets:
            DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
            DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
            SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

Or using an AWS registry:

jobs:
    build:
        name: Build with Picasso
        uses: eduNEXT/picasso/.github/workflows/build.yml@main
        with:
            STRAIN_REPOSITORY: edunext/build-manifests
            STRAIN_REPOSITORY_BRANCH: dev/test-latest-image
            STRAIN_PATH: redwood/base
            SERVICE: mfe
            ENABLE_LIMIT_BUILDKIT_PARALLELISM: false
        secrets:
            SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
            AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
            AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
            AWS_REGION: ${{ secrets.AWS_REGION }}