Skip to content

Commit 480406d

Browse files
kabalinkabalin
committed
Add GitHub Actions example and docs.
1 parent ea8e826 commit 480406d

File tree

6 files changed

+304
-11
lines changed

6 files changed

+304
-11
lines changed

‎docs/CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ The format of this change log follows the advice given at [Keep a CHANGELOG](htt
2020
- Updated project dependencies to current [moodle-local_moodlecheck](https://github.com/moodlehq/moodle-local_moodlecheck) and [moodle-local_ci](https://github.com/moodlehq/moodle-local_ci) versions.
2121

2222
### Added
23-
- Detect existence of legacy php-webdriver, and use a different Firefox image when it is in use
23+
- Detect existence of legacy php-webdriver, and use a different Firefox image when it is in use.
24+
- GitHub Actions use manual and example.
2425

2526
## [3.0.3] - 2020-10-16
2627
### Changed

‎docs/GHAFileExplained.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
layout: page
3+
title: GitHub Actions CI workflow file explained
4+
---
5+
6+
Below is the
7+
[gha.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha.dist.yml)
8+
file with comments added to explain what each section is doing. For additional
9+
information please refer to [workflow syntax reference](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions).
10+
11+
If you are familiar with Travis, this should be strightforward to understand
12+
the syntax, you may find this [migration
13+
manual](https://docs.github.com/en/actions/learn-github-actions/migrating-from-travis-ci-to-github-actions)
14+
useful.
15+
16+
```yaml
17+
# Title of the workflow
18+
name: Moodle Plugin CI
19+
20+
# Run this workflow every time a new commit pushed to your repository or PR
21+
# created.
22+
on: [push, pull_request]
23+
24+
jobs:
25+
# Set the job key. The key is displayed as the job name
26+
# when a job name is not provided
27+
test:
28+
# Virtual environment to use.
29+
runs-on: ubuntu-18.04
30+
31+
# DB services you need for testing.
32+
services:
33+
postgres:
34+
image: postgres:9.6
35+
env:
36+
POSTGRES_USER: 'postgres'
37+
POSTGRES_HOST_AUTH_METHOD: 'trust'
38+
ports:
39+
- 5432:5432
40+
options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3
41+
mariadb:
42+
image: mariadb:10
43+
env:
44+
MYSQL_USER: 'root'
45+
MYSQL_ALLOW_EMPTY_PASSWORD: "true"
46+
ports:
47+
- 3306:3306
48+
options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3
49+
50+
# Determines build matrix. This is a list of PHP versions, databases and
51+
# branches to test our project against. For each combination a separate
52+
# build will be created. For example below 6 builds will be created in
53+
# total (7.2-pgsql, 7.2-mariadb, 7.3-pgsql, 7.3-mariadb, etc.). If we add
54+
# another branch, total number of builds will become 12.
55+
strategy:
56+
fail-fast: false
57+
matrix:
58+
php: ['7.2', '7.3', '7.4']
59+
moodle-branch: ['MOODLE_310_STABLE']
60+
database: [pgsql, mariadb]
61+
62+
# There is an alterantive way allowing to define explicitly define which php, moodle-branch
63+
# and database to use:
64+
#
65+
# matrix:
66+
# include:
67+
# - php: '7.4'
68+
# moodle-branch: 'MOODLE_310_STABLE'
69+
# database: pgsql
70+
# - php: '7.3'
71+
# moodle-branch: 'MOODLE_310_STABLE'
72+
# database: mariadb
73+
# - php: '7.2'
74+
# moodle-branch: 'MOODLE_39_STABLE'
75+
# database: pgsql
76+
77+
steps:
78+
# Check out this repository code in ./plugin directory
79+
- name: Check out repository code
80+
uses: actions/checkout@v2
81+
with:
82+
path: plugin
83+
84+
# Install PHP of required version. For possible options see https://github.com/shivammathur/setup-php
85+
- name: Setup PHP ${{ matrix.php }}
86+
uses: shivammathur/setup-php@v2
87+
with:
88+
php-version: ${{ matrix.php }}
89+
coverage: none
90+
91+
# Install this project into a directory called "ci", updating PATH and
92+
# locale.
93+
- name: Initialise moodle-plugin-ci
94+
run: |
95+
composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3
96+
echo $(cd ci/bin; pwd) >> $GITHUB_PATH
97+
echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH
98+
sudo locale-gen en_AU.UTF-8
99+
100+
# Run the default install.
101+
# Optionally, it is possible to specify a different Moodle repo to use
102+
# (git://github.com/moodle/moodle.git is used by default) and define
103+
# ignore directives or any other env vars for install step.
104+
#
105+
# env:
106+
# MOODLE_REPO=git://github.com/username/moodle.git
107+
# IGNORE_PATHS: 'ignore'
108+
# IGNORE_NAMES: 'ignore_name.php'
109+
# MUSTACHE_IGNORE_NAMES: 'broken.mustache'
110+
- name: Install moodle-plugin-ci
111+
run: |
112+
moodle-plugin-ci install --plugin ./plugin --db-host=127.0.0.1
113+
env:
114+
DB: ${{ matrix.database }}
115+
MOODLE_BRANCH: ${{ matrix.moodle-branch }}
116+
117+
# Steps that are run for the purpose of testing. Any of these steps
118+
# can be re-ordered or removed to your liking. And of course, you can
119+
# add any of your own custom steps.
120+
- name: PHP Lint
121+
if: ${{ always() }} # prevents CI run stopping if step failed.
122+
run: moodle-plugin-ci phplint
123+
124+
- name: PHP Copy/Paste Detector
125+
continue-on-error: true # This step will show errors but will not fail
126+
if: ${{ always() }}
127+
run: moodle-plugin-ci phpcpd
128+
129+
- name: PHP Mess Detector
130+
continue-on-error: true
131+
if: ${{ always() }}
132+
run: moodle-plugin-ci phpmd
133+
134+
- name: Moodle Code Checker
135+
if: ${{ always() }}
136+
run: moodle-plugin-ci codechecker --max-warnings 0
137+
138+
- name: Moodle PHPDoc Checker
139+
if: ${{ always() }}
140+
run: moodle-plugin-ci phpdoc
141+
142+
- name: Validating
143+
if: ${{ always() }}
144+
run: moodle-plugin-ci validate
145+
146+
- name: Check upgrade savepoints
147+
if: ${{ always() }}
148+
run: moodle-plugin-ci savepoints
149+
150+
- name: Mustache Lint
151+
if: ${{ always() }}
152+
run: moodle-plugin-ci mustache
153+
154+
- name: Grunt
155+
if: ${{ always() }}
156+
run: moodle-plugin-ci grunt --max-lint-warnings 0
157+
158+
- name: PHPUnit tests
159+
if: ${{ always() }}
160+
run: moodle-plugin-ci phpunit
161+
162+
- name: Behat features
163+
if: ${{ always() }}
164+
run: moodle-plugin-ci behat --profile chrome
165+
```

‎docs/Help.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ changed. Also a good place to look for new goodies.
1010

1111
## Help topics
1212

13-
* [Travis CI file explained](TravisFileExplained.md): every line of the `.travis.yml` file explained.
13+
* [Travis CI file explained](TravisFileExplained.md): every line of the `.travis.dist.yml` file explained.
14+
* [GitHub Actions workflow file explained](GHAFileExplained.md): every line of the `gha.dist.yml` file explained.
1415
* [Add extra Moodle configs](AddExtraConfig.md): how to add extra configs to Moodle `config.php`.
1516
* [Add extra plugins](AddExtraPlugins.md): how to add plugin dependencies to Moodle.
1617
* [Ignoring files](IgnoringFiles.md): how to ignore files that might be causing failures.

‎docs/ReleaseNewVersion.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,10 @@ Prior to tagging a release, ensure the following have been updated:
1010

1111
* The `CHANGELOG.md` needs to be up-to-date. In addition, the _Unreleased_ section needs to be updated
1212
with the version being released. Also update the _Unreleased_ link at the bottom with the new version number.
13-
* If this is a new major version, then the `.travis.dist.yml` and `doc/TravisFileExplained.md` need to be updated
14-
to use the new major version. Any other version will automatically be used.
13+
* If this is a new major version, then CI tool example files and its docs need
14+
to be updated to use the new major version (e.g. for Travis CI make changes
15+
in `.travis.dist.yml` and `doc/TravisFileExplained.md`). Any other version
16+
will automatically be used.
1517

1618
When all the changes above have been performed, push them straight upstream to
1719
`master` or create a standard PR to get them reviewed and incorporated

‎docs/index.md‎

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -37,30 +37,50 @@ Please know older versions (1 and 2) are no longer getting new features and may
3737

3838
## Getting started
3939

40-
Follow these steps to get your Moodle plugin building in Travis CI.
40+
Follow steps to get your Moodle plugin building in CI tool of your choice.
4141

42-
### Step 1
42+
### Travis CI
43+
44+
#### Step 1
4345

4446
Sign into [Travis CI](https://travis-ci.com) with your GitHub account. Once you’re signed in, and Travis CI will have
4547
synchronized your repositories from GitHub. Go to your [profile](https://travis-ci.com/profile) page and enable Travis CI
4648
for the plugin you want to build. Now whenever your plugin receives an update or gets a new pull request, Travis CI will
4749
run a build to make sure nothing broke.
4850

49-
### Step 2
51+
#### Step 2
5052

5153
Copy the [.travis.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/.travis.dist.yml) file into the
5254
root of your plugin and rename it to `.travis.yml`. Now might be a good time to review the `.travis.yml` contents and
5355
remove anything that is not needed. See this [help document](TravisFileExplained.md) for an explanation about the
5456
contents of the this file. Once you have added the `.travis.yml` file, commit and push up to GitHub, to trigger a
5557
Travis CI build. Navigate back to [Travis CI](https://travis-ci.com) to see if your build passes or fails.
5658

57-
### Step 3
59+
### GitHub Actions
60+
61+
#### Step 1
62+
63+
Copy [gha.dist.yml](https://github.com/moodlehq/moodle-plugin-ci/blob/master/gha.dist.yml) file to `.github/workflows` directory
64+
in your project. You can give this file any name, e.g. `moodle-ci.yml` which we use in this document. Review the `moodle-ci.yml` contents and
65+
remove anything that is not needed. See this [help document](GHAFileExplained.md) for an explanation about the
66+
contents of the this file. Once you have added the `.github/workflows/moodle-ci.yml` file, commit and push up to GitHub, to trigger a
67+
CI build.
68+
69+
#### Step 2
70+
71+
On GitHub, navigate to the main page of the repository. Under your repository
72+
name, click Actions tab and see your build status. You may find this [Quick
73+
Start manual](https://docs.github.com/en/actions/quickstart#viewing-your-workflow-results)
74+
useful. Now whenever you push commits to your plugin repo or it gets a new
75+
pull request, GitHub will run a build to make sure nothing broke.
76+
77+
### Getting more of CI
5878

59-
Congratulations, you are building on Travis CI! Next steps on your continuous build journey include:
79+
Congratulations, you are running CI tests on your plugin! Next steps on your continuous build journey include:
6080

6181
* Reviewing the [help documentation](Help.md) to further improve and customize your build.
62-
* Resolve any build errors you may currently have. Get to that ever rewarding Green Build status.
63-
* Show off your build status by [adding the badge to your plugin's README file](https://docs.travis-ci.com/user/status-images/).
82+
* Resolve any build errors you may currently have. Get to that ever rewarding Green Build status.
83+
* Show off your build status by adding the badge to your plugin's README file.
6484
* Write new tests to increase your code coverage.
6585
* Enjoy your favorite beverage because you no longer have to waste time manually testing your plugin!
6686

‎gha.dist.yml‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
name: Moodle Plugin CI
2+
3+
on: [push, pull_request]
4+
5+
jobs:
6+
test:
7+
runs-on: ubuntu-18.04
8+
9+
services:
10+
postgres:
11+
image: postgres:9.6
12+
env:
13+
POSTGRES_USER: 'postgres'
14+
POSTGRES_HOST_AUTH_METHOD: 'trust'
15+
ports:
16+
- 5432:5432
17+
options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 3
18+
mariadb:
19+
image: mariadb:10
20+
env:
21+
MYSQL_USER: 'root'
22+
MYSQL_ALLOW_EMPTY_PASSWORD: "true"
23+
ports:
24+
- 3306:3306
25+
options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 3
26+
27+
strategy:
28+
fail-fast: false
29+
matrix:
30+
php: ['7.2', '7.3', '7.4']
31+
moodle-branch: ['MOODLE_310_STABLE']
32+
database: [pgsql, mariadb]
33+
34+
steps:
35+
- name: Check out repository code
36+
uses: actions/checkout@v2
37+
with:
38+
path: plugin
39+
40+
- name: Setup PHP ${{ matrix.php }}
41+
uses: shivammathur/setup-php@v2
42+
with:
43+
php-version: ${{ matrix.php }}
44+
coverage: none
45+
46+
- name: Initialise moodle-plugin-ci
47+
run: |
48+
composer create-project -n --no-dev --prefer-dist moodlehq/moodle-plugin-ci ci ^3
49+
echo $(cd ci/bin; pwd) >> $GITHUB_PATH
50+
echo $(cd ci/vendor/bin; pwd) >> $GITHUB_PATH
51+
sudo locale-gen en_AU.UTF-8
52+
53+
- name: Install moodle-plugin-ci
54+
run: |
55+
moodle-plugin-ci install --plugin ./plugin --db-host=127.0.0.1
56+
env:
57+
DB: ${{ matrix.database }}
58+
MOODLE_BRANCH: ${{ matrix.moodle-branch }}
59+
60+
- name: PHP Lint
61+
if: ${{ always() }}
62+
run: moodle-plugin-ci phplint
63+
64+
- name: PHP Copy/Paste Detector
65+
continue-on-error: true # This step will show errors but will not fail
66+
if: ${{ always() }}
67+
run: moodle-plugin-ci phpcpd
68+
69+
- name: PHP Mess Detector
70+
continue-on-error: true # This step will show errors but will not fail
71+
if: ${{ always() }}
72+
run: moodle-plugin-ci phpmd
73+
74+
- name: Moodle Code Checker
75+
if: ${{ always() }}
76+
run: moodle-plugin-ci codechecker --max-warnings 0
77+
78+
- name: Moodle PHPDoc Checker
79+
if: ${{ always() }}
80+
run: moodle-plugin-ci phpdoc
81+
82+
- name: Validating
83+
if: ${{ always() }}
84+
run: moodle-plugin-ci validate
85+
86+
- name: Check upgrade savepoints
87+
if: ${{ always() }}
88+
run: moodle-plugin-ci savepoints
89+
90+
- name: Mustache Lint
91+
if: ${{ always() }}
92+
run: moodle-plugin-ci mustache
93+
94+
- name: Grunt
95+
if: ${{ always() }}
96+
run: moodle-plugin-ci grunt --max-lint-warnings 0
97+
98+
- name: PHPUnit tests
99+
if: ${{ always() }}
100+
run: moodle-plugin-ci phpunit
101+
102+
- name: Behat features
103+
if: ${{ always() }}
104+
run: moodle-plugin-ci behat --profile chrome

0 commit comments

Comments
 (0)