| 1 |
Postgres Continuous Integration (CI) |
| 2 |
==================================== |
| 3 |
|
| 4 |
Postgres has two forms of CI: |
| 5 |
|
| 6 |
1) All supported branches in the main postgres repository are continuously |
| 7 |
tested via the buildfarm. As this covers only the main repository, it |
| 8 |
cannot be used during development of features. |
| 9 |
|
| 10 |
For details see https://buildfarm.postgresql.org/ |
| 11 |
|
| 12 |
2) For not yet merged development work, CI can be enabled for some git hosting |
| 13 |
providers. This allows developers to test patches on a number of platforms |
| 14 |
before they are merged (or even submitted). |
| 15 |
|
| 16 |
|
| 17 |
Configuring CI on personal repositories |
| 18 |
======================================= |
| 19 |
|
| 20 |
Currently postgres contains CI support utilizing cirrus-ci. cirrus-ci |
| 21 |
currently is only available for github. |
| 22 |
|
| 23 |
|
| 24 |
Enabling cirrus-ci in a github repository |
| 25 |
========================================= |
| 26 |
|
| 27 |
To enable cirrus-ci on a repository, go to |
| 28 |
https://github.com/marketplace/cirrus-ci and select "Public |
| 29 |
Repositories". Then "Install it for free" and "Complete order". The next page |
| 30 |
allows to configure which repositories cirrus-ci has access to. Choose the |
| 31 |
relevant repository and "Install". |
| 32 |
|
| 33 |
See also https://cirrus-ci.org/guide/quick-start/ |
| 34 |
|
| 35 |
Once enabled on a repository, future commits and pull-requests in that |
| 36 |
repository will automatically trigger CI builds. These are visible from the |
| 37 |
commit history / PRs, and can also be viewed in the cirrus-ci UI at |
| 38 |
https://cirrus-ci.com/github/<username>/<reponame>/ |
| 39 |
|
| 40 |
Hint: all build log files are uploaded to cirrus-ci and can be downloaded |
| 41 |
from the "Artifacts" section from the cirrus-ci UI after clicking into a |
| 42 |
specific task on a build's summary page. |
| 43 |
|
| 44 |
|
| 45 |
Images used for CI |
| 46 |
================== |
| 47 |
|
| 48 |
To keep CI times tolerable, most platforms use pre-generated images. Some |
| 49 |
platforms use containers, others use full VMs. Images for both are generated |
| 50 |
separately from CI runs, otherwise each git repository that is being tested |
| 51 |
would need to build its own set of containers, which would be wasteful (both |
| 52 |
in space and time. |
| 53 |
|
| 54 |
These images are built, on a daily basis, from the specifications in |
| 55 |
github.com/anarazel/pg-vm-images/ |
| 56 |
|
| 57 |
|
| 58 |
Controlling CI via commit messages |
| 59 |
================================== |
| 60 |
|
| 61 |
The behavior of CI can be controlled by special content in commit |
| 62 |
messages. Currently the following controls are available: |
| 63 |
|
| 64 |
- ci-os-only: {(freebsd|linux|macos|mingw|netbsd|openbsd|windows)} |
| 65 |
|
| 66 |
Only runs CI on operating systems specified. This can be useful when |
| 67 |
addressing portability issues affecting only a subset of platforms. |
| 68 |
|
| 69 |
|
| 70 |
Using custom compute resources for CI |
| 71 |
===================================== |
| 72 |
|
| 73 |
When running a lot of tests in a repository, cirrus-ci's free credits do not |
| 74 |
suffice. In those cases a repository can be configured to use other |
| 75 |
infrastructure for running tests. To do so, the REPO_CI_CONFIG_GIT_URL |
| 76 |
variable can be configured for the repository in the cirrus-ci web interface, |
| 77 |
at https://cirrus-ci.com/github/<user or organization>. The file referenced |
| 78 |
(see https://cirrus-ci.org/guide/programming-tasks/#fs) by the variable can |
| 79 |
overwrite the default execution method for different operating systems, |
| 80 |
defined in .cirrus.yml, by redefining the relevant yaml anchors. |
| 81 |
|
| 82 |
Custom compute resources can be provided using |
| 83 |
- https://cirrus-ci.org/guide/supported-computing-services/ |
| 84 |
- https://cirrus-ci.org/guide/persistent-workers/ |
| 85 |
|
| 86 |
|
| 87 |
Enabling manual tasks by default |
| 88 |
================================ |
| 89 |
|
| 90 |
Some tasks are not triggered automatically by default, to avoid using up CI |
| 91 |
credits too quickly. This can be changed on the repository level, e.g. when |
| 92 |
custom compute resources are configured. |
| 93 |
|
| 94 |
The following repository level environment variables are recognized: |
| 95 |
- REPO_CI_AUTOMATIC_TRIGGER_TASKS - space-separated list of (mingw|netbsd|openbsd) |