Postgres Continuous Integration (CI)
====================================

Postgres has two forms of CI:

1) All supported branches in the main postgres repository are continuously
   tested via the buildfarm. As this covers only the main repository, it
   cannot be used during development of features.

   For details see https://buildfarm.postgresql.org/

2) For not yet merged development work, CI can be enabled for some git hosting
   providers. This allows developers to test patches on a number of platforms
   before they are merged (or even submitted).


Configuring CI on personal repositories
=======================================

Currently postgres contains CI support utilizing GitHub Actions.


Configuring CI use for a GitHub repository
==========================================

The GitHub Actions based CI workflow may or may not be active by default,
depending on when the repository was forked.

To disable the CI workflow on a repository, navigate to
https://github.com/<username>/<reponame>/actions/workflows/pg-ci.yml
and click on the '...' on the top right and choose 'Disable workflow'.

To enable the workflow, go to the same page and click on "Enable workflow" at
the top.

However, to avoid issues with the thousands of forks of the postgres/postgres
repository starting to run CI the next time the forks re-synchronize with the
postgres/postgres, each repository needs to explicitly opt-in to actually run
the full CI tests.

To opt into CI, go to
https://github.com/<username>/<reponame>/settings/variables/actions and
create a new repository variable named PG_CI_ENABLED, with the value 1.


Viewing CI results in a GitHub repository
=========================================

CI runs are visible at https://github.com/<username>/<reponame>/actions

The high-level status of workflow runs on public repositories are visible
without being logged into GitHub, however details including logs require being
logged in.


Containers / Images used for CI
===============================

To keep CI times tolerable, several platforms use pre-generated containers /
images. The containers and images are generated separately from CI runs,
otherwise each git repository that is being tested would need to build its own
set of containers, which would be wasteful (both in space and time).

These containers / images are built, on a daily basis, from the specifications
in github.com/anarazel/pg-vm-images/


Controlling CI via commit messages
==================================

The behavior of CI can be controlled by special content in commit
messages. Currently the following controls are available:

- ci-os-only: {(compilerwarnings|linux|macos|mingw|sanitycheck|windows)}

  Only runs CI on operating systems specified. This can be useful when
  addressing portability issues affecting only a subset of platforms.
