...

• When jobs are triggered by different scenarios (for example, pull request vs. scheduled), split them into separate workflows.

• When one job depends on the status or output of other jobs, you may need to combine them into a single workflow.

• When jobs share a related purpose (for example, code quality checks), consider grouping them into a single workflow.

• When using a matrix and required checks, it can simplify configuration to collect the matrix steps into a final success step, then require just the success step. An example of applying this pattern is in https://github.com/openedx/edx-platform/pull/31024.

• If many repos across Open edX will be using the same workflow, consider making a reusable workflow—even if all your workflow does is call a non-openedx reusable workflow! This will allow coordinated upgrades.

  • Get your workflow working, then make a PR against openedx/.github but use the workflow_call trigger and inputs.

  • In the new workflow, be sure to pin any workflows it depends on to commits (ideally) or tags.

  • In your repo, depend on the master version of the new reusable workflow. This provides a central point of indirection that allows automatically upgrading all dependent repos to newer versions of actions.

Testing

• https://github.com/nektos/act allows you to run and test your actions locally (with some limitations)

• If you’re making a new GitHub workflow that needs to be manually runnable (on: workflow_dispatch), GitHub won’t offer to run it until it has been run at least once. You can get out of this Catch-22 by temporarily adding push as one of the triggers, then pushing that to your branch. Now GitHub knows about it, and you can remove push and then use the GH CLI to invoke the version that's on your branch: gh workflow run my-new-workflow.yml --ref my-working-branch -f param1=value1 -f param2=value2

Other advice

• Include an on: workflow_dispatch trigger. Why wouldn’t you want to be able to manually start an action if needed?

• If you have many required checks, it can be more convenient and less error-prone to aggregate them into a “success” step, and just require the success step. See edx-platform’s unit-tests.yml action for how it works: https://github.com/openedx/edx-platform/blob/f4566cdc7a89b788f8981c637c57c0453e857a3c/.github/workflows/unit-tests.yml#L77-L91

• Actions now (Jan 2023) can have configuration variables: https://github.blog/changelog/2023-01-10-github-actions-support-for-configuration-variables-in-workflows/. Previously, this was done with secrets, but it’s not good to store non-secret information in secrets.

• Jobs can auto-cancel when changes are pushed to the same branch. Use the concurrency clause to control what jobs get canceled when a new job begins: https://docs.github.com/en/actions/using-jobs/using-concurrency.

• Review existing actions and model workflows to understand what’s possible and avoid reinventing existing well-supported code. One good resource for this is https://github.com/sdras/awesome-actions .

...