src/tools/ci/README

   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|windows|mingw)}
  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/