🔄 Setup Continuous Integration using GitHub Actions

:mag: Overview

To build a robust extension for Discourse, it can be wise to include Continuous Integration (CI) into your plugin or theme-component. This will help to detect errors early on and lessen the chances of bugs in your code.

Setting up a CI workflow using GitHub Actions to automate builds and testing is an approach the Discourse team uses on all our components, and we recommend you do the same.

:gear: Setting it up

To add automated workflows for GitHub actions to detect, you need to create a .github/workflows folder in the root directory of your repository.

Inside the workflows folder you can define a set of automations that GitHub actions will need to run. For instance, these could be .yml files for linting and tests.

We’ve created template workflows for both plugins and theme components which you can make use of. In the template’s skeleton repository, on GitHub you can click the Use this template button to create a plugin/theme component repository based on the template.

Alternatively, if you already have a project you’d like to add the workflows to, simply copy the respective linting and test workflows into your repository’s .github/workflows/ folder:

:electric_plug: Plugins:

:point_up: The above templates are found in the discourse-plugin-skeleton repo, and it is recommended you track that repository for changes.

:jigsaw: Theme Components:

:point_up: The above templates are found in the discourse-theme-skeleton repo, and it is recommended you track that repository for changes.

:tada: Voila! You’re all setup! Simply, create a commit or a PR to your repository and GitHub actions will auto-detect the workflows and begin running the jobs.

GitHub actions will show a breakdown of each test and after running it will indicate either a :white_check_mark: or :x: depending on if the test passed or failed.

If a test failed, clicking on the details will give you a some information on what failed which may give you clues on what’s wrong with your code and what needs to be fixed.

See example

:white_check_mark: Add your own tests

For plugin and components tests to work effectively, its important that you write tests for your plugin or theme component.

For details on how to write front-end tests with EmberJS see:

For more details on writing test RSpec tests with Rails see:

:bulb: Examples

For your benefit, we’ve picked out a couple examples of plugins and theme components that have some robust testing integrated:

5 Likes

You might mention GitHub - discourse/discourse-theme-skeleton: Template for Discourse themes explicitly and note that you should watch it to take note of changes in those files.

3 Likes

Hopefully the reusable workflows can get merged, making this part less relevant as new repositories made from the template will use the workflows from the template repository directly.

2 Likes

Thanks @pfaffman and @Simon_Manning, good points. I’ve updated the OP accordingly.

4 Likes