| Daniel P. Berrangé | 0e103a6 | 2021-07-09 15:29:32 +0100 | [diff] [blame] | 1 | Cirrus CI integration |
| 2 | ===================== |
| 3 | |
| 4 | GitLab CI shared runners only provide a docker environment running on Linux. |
| 5 | While it is possible to provide private runners for non-Linux platforms this |
| 6 | is not something most contributors/maintainers will wish to do. |
| 7 | |
| 8 | To work around this limitation, we take advantage of `Cirrus CI`_'s free |
| 9 | offering: more specifically, we use the `cirrus-run`_ script to trigger Cirrus |
| 10 | CI jobs from GitLab CI jobs so that Cirrus CI job output is integrated into |
| 11 | the main GitLab CI pipeline dashboard. |
| 12 | |
| 13 | There is, however, some one-time setup required. If you want FreeBSD and macOS |
| 14 | builds to happen when you push to your GitLab repository, you need to |
| 15 | |
| 16 | * set up a GitHub repository for the project, eg. ``yourusername/qemu``. |
| 17 | This repository needs to exist for cirrus-run to work, but it doesn't need to |
| 18 | be kept up to date, so you can create it and then forget about it; |
| 19 | |
| 20 | * enable the `Cirrus CI GitHub app`_ for your GitHub account; |
| 21 | |
| 22 | * sign up for Cirrus CI. It's enough to log into the website using your GitHub |
| 23 | account; |
| 24 | |
| 25 | * grab an API token from the `Cirrus CI settings`_ page; |
| 26 | |
| 27 | * it may be necessary to push an empty ``.cirrus.yml`` file to your github fork |
| 28 | for Cirrus CI to properly recognize the project. You can check whether |
| 29 | Cirrus CI knows about your project by navigating to: |
| 30 | |
| 31 | ``https://cirrus-ci.com/yourusername/qemu`` |
| 32 | |
| 33 | * in the *CI/CD / Variables* section of the settings page for your GitLab |
| 34 | repository, create two new variables: |
| 35 | |
| 36 | * ``CIRRUS_GITHUB_REPO``, containing the name of the GitHub repository |
| 37 | created earlier, eg. ``yourusername/qemu``; |
| 38 | |
| 39 | * ``CIRRUS_API_TOKEN``, containing the Cirrus CI API token generated earlier. |
| 40 | This variable **must** be marked as *Masked*, because anyone with knowledge |
| 41 | of it can impersonate you as far as Cirrus CI is concerned. |
| 42 | |
| 43 | Neither of these variables should be marked as *Protected*, because in |
| 44 | general you'll want to be able to trigger Cirrus CI builds from non-protected |
| 45 | branches. |
| 46 | |
| 47 | Once this one-time setup is complete, you can just keep pushing to your GitLab |
| 48 | repository as usual and you'll automatically get the additional CI coverage. |
| 49 | |
| 50 | |
| 51 | .. _Cirrus CI GitHub app: https://github.com/marketplace/cirrus-ci |
| 52 | .. _Cirrus CI settings: https://cirrus-ci.com/settings/profile/ |
| 53 | .. _Cirrus CI: https://cirrus-ci.com/ |
| 54 | .. _cirrus-run: https://github.com/sio/cirrus-run/ |
