Home | History | Annotate | Line # | Download | only in docs 
      1 .. _AddingNewCIJobs:
      2 
      3 ==================
      4 Adding New CI Jobs
      5 ==================
      6 
      7 .. contents::
      8   :local:
      9 
     10 Adding The Job
     11 ==============
     12 
     13 libc++ uses Buildkite for running its CI. Setting up new CI jobs is easy, and
     14 these jobs can run either on our existing infrastructure, or on your own.
     15 
     16 If 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
     18 own agents. Make sure you tag your agents in a way that you'll be able
     19 to recognize them when defining your job below. Finally, in order for the
     20 agent to register itself to Buildkite, it will need a ``BUILDKITE_AGENT_TOKEN``.
     21 Please contact a maintainer to get your token.
     22 
     23 Then, simply add a job to the Buildkite pipeline by editing ``libcxx/utils/ci/buildkite-pipeline.yml``.
     24 Take a look at how the surrounding jobs are defined and do something similar.
     25 An 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     retry:
     36       automatic:
     37         - exit_status: -1  # Agent was lost
     38           limit: 2
     39 
     40 If you've created your own agents, you should provide the tag that you used
     41 when creating them in the ``queue`` entry -- this will instruct Buildkite to
     42 run that job only on agents that have that tag.
     43 
     44 We try to keep the pipeline definition file as simple as possible, and to
     45 keep any script used for CI inside ``libcxx/utils/ci``. This ensures that
     46 it's possible to reproduce CI issues locally with ease, understanding of
     47 course that some setups may require access to special hardware that is not
     48 available.
     49 
     50 Testing Your New Job
     51 ====================
     52 
     53 Testing your new job is easy -- once your agent is set up (if any), just open
     54 a code review and the libc++ CI pipeline will run, including any changes you
     55 might have made to the pipeline definition itself.
     56 
     57 Service Level Agreement
     58 =======================
     59 
     60 To keep the libc++ CI useful for everyone, we aim for a quick turnaround time
     61 for all CI jobs. This allows the overall pipeline to finish in a reasonable
     62 amount of time, which is important because it directly affects our development
     63 velocity. We also try to make sure that jobs run on reliable infrastructure in
     64 order to avoid flaky failures, which reduce the value of CI for everyone.
     65 
     66 We may be reluctant to add and support CI jobs that take a long time to finish
     67 or that are too flaky.
     68