GitHub Actions#
This page explains GitHub Actions, how we use them in the Open edX project, and some tips on troubleshooting.
What Is GitHub Actions?#
GitHub Actions is a continuous integration and continuous delivery (CI/CD) platform that allows you to automate your build, test, and deployment pipeline. You can create workflows that build and test every pull request to your repository, or deploy merged pull requests to production.
GitHub Actions goes beyond just DevOps and lets you run workflows when other events happen in your repository. For example, you can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository.
How Does the Open edX Project Use Them?#
The Open edX project uses Actions to automate test builds on pull requests, as
well as to create other types of automations beyond testing. Once such workflow
is the fix Transifex resource names workflow in the openedx-translation repo.
hat runs every time the transifex.yml or extract-translation-source-files.yml
files are updated on the main branch, on workflow dispatch (when triggered
manually), and on the first of every month. We also use Actions to ensure
everyone is covered by a CLA, to allow anyone to assign an Issue to themselves
by commenting assign me in a comment, linting commit messages, ensuring our
requirements are up to date, and in many other creative ways.
You can check out the workflows available to all Open edX repositories in the
.github repo; many repos define their own workflows in their
.github/workflows directory.
Understanding and Troubleshooting Builds#
A “build” is a name for a collection of GitHub actions that run on a single commit. These “builds” typically consist of multiple GitHub actions: one or more test runners, a CLA check, commitlint, possibly a ReadTheDocs build for repos with documentation, and various other types depending on the repo’s purpose and primary language.
Reading Build Statuses#
At the bottom of your pull request, there will be one or more builds run and a widget that displays the status of the run:
Clicking the “Details” link on the right of each build will give you some more context as to why it failed.
If the “openedx/cla” check fails, you’ll need to either sign the Open edX CLA or have your employer add you to their entity CLA agreement. Please talk to your employer for guidance if you’re unsure.
If the “Lint Commit Messages” check fails, you need to rewrite your commit message using Conventional Commits (see OEP-51: Conventional Commits).
Failed Builds#
Click on an individual failed Action (red X) to be brought to the build page.
Kicking Off Builds#
Actions run automatically on a pull request when a new commit is pushed to the branch, or the branch is rebased. Sometimes Actions get stuck (a yellow circle that never goes away) or fail when you think it should pass - in this case, you have a few options:
If possible, rebase the branch atop master/main and force-push to generate a new build
If you have permissions, you can visit the build page for a failed build and click the “Re-run jobs” button in the top right corner
Push an empty commit to trigger a new build (but rebase it away before merging):
git commit --allow-empty -m "Empty-Commit"
Try closing and re-opening the pull request to trigger a new build.
Please do not close your PR and open a new one in an attempt to get a build to pass, unless asked to do so. This removes a lot of history from the new PR, making it challenging to understand the previous review history and requested changes.
Maintenance chart
Review Date |
Working Group Reviewer |
Release |
Test situation |