Picasso Workflow

Simplifies the build of Open edX Docker images for Tutor environments, providing a solution that integrates directly with GitHub Actions.

Purpose

Picasso is a tool designed to help teams simplify the build process for the Open edX Docker images, tailored explicitly for use in Tutor environments. It enables the addition of custom behaviors and features through the internal plugin tutor-contrib-picasso, allowing for additional flexibility during the build process.

This workflow integrates seamlessly with existing internal workflows, enabling it to be invoked in custom jobs. It leverages Tutor to build images starting from the Olive version, which can be deployed across both production and development environments. This ensures consistency in managing multiple environments while simplifying the overall process.

With Picasso, teams can build custom Open edX images with additional functionality, making it easier to maintain, extend, and deploy environments using modern CI/CD practices.

Workflow Overview

The Picasso Workflow is designed to build Open edX Docker images for Tutor environments.

Key features of the Picasso Workflow include:

• Runs on GitHub-hosted runners: By default, the workflow uses ubuntu-latest runners to execute jobs. This can't be changed to self-hosted runners for the time being.
• Builds and pushes Docker images: The workflow pushes images to Dockerhub by default. This can be customized to push images to other registries.
• Supports multiple services: You can specify the service to build (e.g., openedx, mfe, codejail, etc.) using the SERVICE input.
• Customizable repository and strain: The workflow allows for specifying the repository, branch, and path to the strain being built. This enables building images from different configurations.
• Configurable BuildKit parallelism: By default, the workflow limits parallelism during the build process to optimize resource usage, although this can be changed using the ENABLE_LIMIT_BUILDKIT_PARALLELISM input. This is useful for low-powered machines, like Github Actions standard runners.
• Private repository access: SSH keys are used to clone private repositories securely. The SSH private key should be stored as a secret in the repository, and must have access to the repository specified in STRAIN_REPOSITORY.
• Extra commands: The workflow allows running additional custom commands with tutor picasso run-extra-commands. For details, refer to the tutor-contrib-picasso documentation.
• Environment setup: The workflow sets up installs necessary plugins like tutor-contrib-picasso, and prepares the environment to build and push Docker images using the Tutor CLI.

Configuration

Before using the workflow, ensure that you have set up the following configurations in your GitHub repository:

Picasso Workflow Configuration

Variable	Description	Type	Source
DOCKERHUB_USERNAME (Optional)	Docker Hub username to push images.	string	Secret
DOCKERHUB_PASSWORD (Optional)	Docker Hub password for login.	string	Secret
AWS_ACCESS_KEY_ID (Optional)	AWS access key ID for pushing images to ECR.	string	Secret
AWS_SECRET_ACCESS_KEY (Optional)	AWS secret access key for pushing images to ECR.	string	Secret
AWS_REGION (Optional)	AWS region for pushing images to ECR.	string	Secret
SSH_PRIVATE_KEY (Required)	SSH private key for repository checkout. This key should have access to the repository specified in STRAIN_REPOSITORY.	string	Secret
STRAIN_REPOSITORY (Required)	The repository to clone the strain from, e.g., edunext/repository-name.	string	Input
STRAIN_REPOSITORY_BRANCH (Required)	The branch to clone the strain from, e.g., main. This branch should contain the version of configuration config.yml file used to build the image.	string	Input
STRAIN_PATH (Required)	The path to the strain within the repository structure, e.g., path/to/strain.	string	Input
SERVICE (Required)	The service name to build, e.g., openedx. This can be any service recognized by the tutor ecosystem.	string	Input
ENABLE_LIMIT_BUILDKIT_PARALLELISM (Optional)	Enables limiting parallelism with buildkit to decrease resource consumption for those setups with low-powered machines. Default is true.	boolean	Input
RUNNER_WORKFLOW_LABEL (Optional)	The label of the runner workflow to use. Default is ubuntu-24.04.	string	Input
PYTHON_VERSION (Optional)	The Python version to use in the workflow. Default is 3.12.	string	Input
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. Default is the latest release major version, e.g., v1.	string	Input

Usage

To use the Picasso Workflow, follow these steps:

1. Ensure your repository calls the Picasso workflow like the one below. This example demonstrates how to build an Open edX image using the Picasso workflow:

   jobs:
     build:
       name: Build Open edX Image
       uses: eduNEXT/picasso/.github/workflows/build.yml@main
       with:
         STRAIN_REPOSITORY: edunext/builds
         STRAIN_REPOSITORY_BRANCH: main
         STRAIN_PATH: redwood/base
         SERVICE: openedx
       secrets:
         DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
         DOCKERHUB_PASSWORD: ${{ secrets.DOCKERHUB_PASSWORD }}
         SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

2. Modify the STRAIN_REPOSITORY, STRAIN_REPOSITORY_BRANCH, STRAIN_PATH, and SERVICE inputs to match your project requirements.

3. You can also set up a custom trigger for the workflow based on your project requirements.

Getting Help

If you encounter any issues with the workflow or need further assistance, please refer to the following resources:

• GitHub Actions documentation for troubleshooting steps.
• You can also open an issue in the Picasso Workflow repository.
• For more information on the workflow, refer to the documentation on Read the Docs.

Contributing

Contributions are welcome and strongly encouraged! Please, open an issue or submit a pull request to suggest changes or improvements to the workflow.

License

This project is licensed under the AGPL-3.0 License. . Please note that no support or maintenance is guaranteed for public users. Any updates, bug fixes, or improvements will be made based on internal priorities, and contributions from the community may not receive immediate attention.

Reporting Security Issues

Please do not report security vulnerabilities in public forums. Instead, email [email protected].