Automated PR Sandbox¶
Settings used for upstream PRs to the repositories under the openedx org, can be found in Upstream Open edX Settings section below. Settings used for OpenCraft's internal/upstream PRs can be found in OpenCraft Internal/Upstream Settings section below.
pr_watcher OpenFAAS function in Grove automatically provisions sandboxes for PRs created by authorized users in the configured repositories. This function is triggered periodically every 15 minutes.
Here are some of the things this function does:
- Periodically checks for new PRs created with the correct label by authorized users in watched repos and provisions sandboxes for them.
- Updates PR sandboxes if changes are detected in the PR.
- Notifies the status of sandbox provisioning as comments on the PR.
- Enables PR authors to configure their sandbox using the PR description.
- Automatically destroys the sandbox when a PR is closed, merged, or if no changes are detected in an open PR for an extended period of time.
This guide is intended to help PR authors understand the automated sandbox workflow and show how to configure and interact with the sandbox and with the
There are two ways to configure watched repositories with this function:
- Forks can be configured dynamically using the pre-defined topic
pr-sandboxes-enabledadded to those repos that need to be watched for a given set of authorized Github orgs. The
GITHUB_WATCHED_ORGANIZATIONSvariable is used to configure the authorized Github orgs.
- Individual forks can be configured directly with the function during deployment of the
pr_watcherfunction using the
We differentiate two different categories of forks that can be configured with the
- Forks of edx-platform repo. Sandboxes for PRs from these forks have the deployment branch configured as source repo/branch of the PR.
- Forks for MFEs. Sandboxes for PRs of these forks have the
edx-platformmaster branch configured as the deployment branch by default unless overridden by the PR author. The source repo/branch of the PR is configured as a custom MFE.
For MFE forks it's important that the repo name starts with
frontend-app-. Otherwise, the function will treat it as an
edx-platform fork. This assumption is based on the naming convention of MFEs.
Authorized Users and Team¶
To prevent abuse of resources, only PRs from authorized users are considered for sandbox creation. Authorized users can either be configured individually or through Github teams. All users belonging to these authorized teams would be treated as authorized users. By using the GitHub teams as the source of users, the user management can be dynamic.
Enable Sandbox for PRs¶
Based on the target branch of a PR, the
pr_watcher function tries to determine which named release of Open edX the PR is intended for. Certain things such as
OPENEDX_COMMON_VERSION and the release version of Tutor and its plugins are configured based on this.
For a PR to be recognized as targting a named release, its target branch should be of the format
opencraft-release/palm.1 are examples of valid names of target branches.
Recognized named releases are limited to
nutmeg and above.
If a named release cannot be determined from the target branch, then
OPENEDX_COMMON_VERSION is set to
master and the
nightly version of Tutor and it's plugins are used. This assumption is applied in order to cover the vast majority of PRs. The
OPENEDX_COMMON_VERSION can be overridden by the PR author.
PR authors can either override existing default configurations or set other configurations values for their sandbox directly from the PR body.
The custom configurations are of two different types:
1. Tutor Configurations¶
Configurations passed directly to tutor and its plugins, such as
These configuration settings need to be added to the PR body in the following format:
2. Grove Configurations¶
These configuration settings are used by Grove itself to configure the sandbox instances, such as
TUTOR_GROVE_WAFFLE_FLAGS, etc. The plugin configuration is described in Grove's Tutor plugin.
Similar to tutor configurations, these can be added to the PR body under
Settings and can be mixed with other tutor configurations. Example:
These are used to set the release-version/branch of Tutor and it's plugins to be used with the sandbox. Although the requirements below are necessary for the PR sandboxes, the PR author could add any other tutor plugins that is needed for the given PR. For example, if a new plugin is developed.
These can be added to the PR body in the following format:
pr_watcher function posts notifications as comments in the PR to notify PR authors about the success/failure status of the sandbox :
- If deployment succeeds, then the LMS URL, Studio URL, current instance configs and current instance requirements are posted along with the success notification
- If deployment fails, then the failure logs, current instance configs and current instance requirements are posted with the failure notification.
Destroying IDLE Sandboxes¶
The sandboxes, especially if the PRs are lasting for many weeks, can consume huge amount of resources. This is mitigated by destroying the sandboxes after a period of inactivity. This period is set to 14 days by default.
This is configurable using the
PR_WATCHER_SANDBOX_DESTROY_CUTOFF_DAYS environment variable when deploying the
The automatic destroy cannot be turned off or extended per sandbox, nor can it be set from the PR description.
Settings for some Use Cases¶
Upstream Open edX Settings¶
- GITHUB_WATCHED_ORGANIZATIONS variable is set to
- GITHUB_AUTHORIZED_TEAMS variable is set to