xref: /aosp_15_r20/external/cronet/third_party/libc++/src/docs/AddingNewCIJobs.rst (revision 6777b5387eb2ff775bb5750e3f5d96f37fb7352b) 
1.. _AddingNewCIJobs:
2
3==================
4Adding New CI Jobs
5==================
6
7.. contents::
8  :local:
9
10Adding The Job
11==============
12
13libc++ uses Buildkite for running its CI. Setting up new CI jobs is easy, and
14these jobs can run either on our existing infrastructure, or on your own.
15
16If you need to run the job on your own machines, please follow the
17`Buildkite guide <https://buildkite.com/docs/agent/v3>`_ to setup your
18own agents. Make sure you tag your agents in a way that you'll be able
19to recognize them when defining your job below. Finally, in order for the
20agent to register itself to Buildkite, it will need a BuildKite Agent token.
21Please contact a maintainer to get your token.
22
23Then, simply add a job to the Buildkite pipeline by editing ``libcxx/utils/ci/buildkite-pipeline.yml``.
24Take a look at how the surrounding jobs are defined and do something similar.
25An example of a job definition is:
26
27.. code-block:: yaml
28
29  - label: "C++11"
30    command: "libcxx/utils/ci/run-buildbot generic-cxx11"
31    artifact_paths:
32      - "**/test-results.xml"
33    agents:
34      queue: "libcxx-builders"
35      os: "linux"
36    retry:
37      [...]
38
39If you create your own agents, put them in the ``libcxx-builders`` queue and
40use agent tags to allow targeting your agents from the Buildkite pipeline
41config appropriately.
42
43We try to keep the pipeline definition file as simple as possible, and to
44keep any script used for CI inside ``libcxx/utils/ci``. This ensures that
45it's possible to reproduce CI issues locally with ease, understanding of
46course that some setups may require access to special hardware that is not
47available.
48
49Finally, add your contact info to ``libcxx/utils/ci/BOT_OWNERS.txt``. This will
50be used to contact you when there are issues with the bot.
51
52Testing Your New Job
53====================
54
55Testing your new job is easy -- once your agent is set up (if any), just open
56a code review and the libc++ CI pipeline will run, including any changes you
57might have made to the pipeline definition itself.
58
59Service Level Agreement
60=======================
61
62To keep the libc++ CI useful for everyone, we aim for a quick turnaround time
63for all CI jobs. This allows the overall pipeline to finish in a reasonable
64amount of time, which is important because it directly affects our development
65velocity. We also try to make sure that jobs run on reliable infrastructure in
66order to avoid flaky failures, which reduce the value of CI for everyone.
67
68We may be reluctant to add and support CI jobs that take a long time to finish
69or that are too flaky.
70