docs: add a page explaining the GitLab CI and the Intel CI
[mesa.git] / docs / ci.rst
1 Continuous Integration & Testing
2 ================================
5 GitLab CI
6 ---------
8 GitLab provides a convenient framework for running commands in response to git pushes.
9 We use it to test merge requests (MRs) before merging them (pre-merge testing),
10 as well as post-merge testing, for everything that hits ``master``
11 (this is necessary because we still allow commits to be pushed outside of MRs,
12 and even then the MR CI runs in the forked repository, which might have been
13 modified and thus is unreliable).
15 The CI runs a number of tests, from trivial build-testing to complex GPU rendering:
17 - Build testing for a number of build systems, configurations and platforms
18 - Sanity checks (``meson test`` & ``scons check``)
19 - Some drivers (softpipe, llvmpipe, freedreno and panfrost) are also tested
20 using `VK-GL-CTS <>`__
22 A typical run takes between 20 and 30 minutes, although it can go up very quickly
23 if the GitLab runners are overwhelmed, which happens sometimes. When it does happen,
24 not much can be done besides waiting it out, or cancel it.
26 Due to limited resources, we currently do not run the CI automatically
27 on every push; instead, we only run it automatically once the MR has
28 been assigned to ``Marge``, our merge bot.
30 If you're interested in the details, the main configuration file is ``.gitlab-ci.yml``,
31 and it references a number of other files in ``.gitlab-ci/``.
33 If the GitLab CI doesn't seem to be running on your fork (or MRs, as they run
34 in the context of your fork), you should check the "Settings" of your fork.
35 Under "CI / CD" → "General pipelines", make sure "Custom CI config path" is
36 empty (or set to the default ``.gitlab-ci.yml``), and that the
37 "Public pipelines" box is checked.
39 If you're having issues with the GitLab CI, your best bet is to ask
40 about it on ``#freedesktop`` on Freenode and tag `Daniel Stone
41 <>`__ (``daniels`` on IRC) or
42 `Eric Anholt <>`__ (``anholt`` on
43 IRC).
46 Intel CI
47 --------
49 The Intel CI is not yet integrated into the GitLab CI.
50 For now, special access must be manually given (file a issue in
51 `the Intel CI configuration repo <>`__
52 if you think you or Mesa would benefit from you having access to the Intel CI).
53 Results can be seen on ` <>`__
54 if you are *not* an Intel employee, but if you are you
55 can access a better interface on
56 ` <>`__.
58 The Intel CI runs a much larger array of tests, on a number of generations
59 of Intel hardware and on multiple platforms (x11, wayland, drm & android),
60 with the purpose of detecting regressions.
61 Tests include
62 `Crucible <>`__,
63 `VK-GL-CTS <>`__,
64 `dEQP <>`__,
65 `Piglit <>`__,
66 `Skia <>`__,
67 `VkRunner <>`__,
68 `WebGL <>`__,
69 and a few other tools.
70 A typical run takes between 30 minutes and an hour.
72 If you're having issues with the Intel CI, your best bet is to ask about
73 it on ``#dri-devel`` on Freenode and tag `Clayton Craft
74 <>`__ (``craftyguy`` on IRC) or
75 `Nico Cortes <>`__ (``ngcortes``
76 on IRC).