taskcluster/docs/cron.rst
author Manuel Rego Casasnovas <rego@igalia.com>
Mon, 19 Nov 2018 18:46:13 +0000
changeset 506778 359ee839f1a358175a0d4d537476d32a7f4a39a4
parent 470150 da8af21b243efa5c5810ee43d947f43865c238e5
permissions -rw-r--r--
Bug 1507805 [wpt PR 14092] - [css-grid] Some fixes on grid-container-scrollbar-* tests, a=testonly Automatic update from web-platform-tests[css-grid] Some fixes on grid-container-scrollbar-* tests * Use Ahem font to avoid weird small pixel differences on iOS. * Fix some typos reported by @fred-wang at https://bugs.webkit.org/show_bug.cgi?id=191656#c14 -- Merge pull request #14092 from mrego/grid-container-scrollbars [css-grid] Some fixes on grid-container-scrollbar-* tests -- wpt-commits: ef7824a8ff88c95d36b31b377fe252f7c56d2da0, 1b543a1083f48c13b25f23a5f23d14f6ade958d4 wpt-pr: 14092

Periodic Taskgraphs
===================

The cron functionality allows in-tree scheduling of task graphs that run
periodically, instead of on a push.

Cron.yml
--------

In the root of the Gecko directory, you will find `.cron.yml`.  This defines
the periodic tasks ("cron jobs") run for Gecko.  Each specifies a name, what to
do, and some parameters to determine when the cron job should occur.

See ``taskcluster/taskgraph/cron/schema.py`` for details on the format and
meaning of this file.

How It Works
------------

The `TaskCluster Hooks Service <https://tools.taskcluster.net/hooks>`_ has a
hook configured for each repository supporting periodic task graphs.  The hook
runs every 15 minutes, and the resulting task is referred to as a "cron task".
That cron task runs `./mach taskgraph cron` in a checkout of the Gecko source
tree.

The mach subcommand reads ``.cron.yml``, then consults the current time
(actually the time the cron task was created, rounded down to the nearest 15
minutes) and creates tasks for any cron jobs scheduled at that time.

Each cron job in ``.cron.yml`` specifies a ``job.type``, corresponding to a
function responsible for creating TaskCluster tasks when the job runs.

Describing Time
---------------

This cron implementation understands the following directives when
describing when to run:

* ``minute``: The minute in which to run, must be in 15 minute increments (see above)
* ``hour``: The hour of the day in which to run, in 24 hour time.
* ``day``: The day of the month as an integer, such as `1`, `16`. Be cautious above `28`, remember February.
* ``weekday``: The day of the week, `Monday`, `Tuesday`, etc. Full length ISO compliant words.

Setting both 'day' and 'weekday' will result in a cron job that won't run very often,
and so is undesirable.

*Examples*

.. code-block:: yaml

    # Never
    when: []

    # 4 AM and 4 PM, on the hour, every day.
    when:
        - {hour: 16, minute: 0}
        - {hour: 4, minute: 0}

    # The same as above, on a single line
    when: [{hour: 16, minute: 0}, {hour: 4, minute: 0}]

    # 4 AM on the second day of every month.
    when:
        - {day: 2, hour: 4, minute: 0}

    # Mondays and Thursdays at 10 AM
    when:
        - {weekday: 'Monday', hour: 10, minute: 0}
        - {weekday: 'Thursday', hour: 10, minute: 0}


Decision Tasks
..............

For ``job.type`` "decision-task", tasks are created based on
``.taskcluster.yml`` just like the decision tasks that result from a push to a
repository.  They run with a distinct ``taskGroupId``, and are free to create
additional tasks comprising a task graph.

Scopes
------

The cron task runs with the sum of all cron job scopes for the given repo.  For
example, for the "sequoia" project, the scope would be
``assume:repo:hg.mozilla.org/projects/sequoia:cron:*``.  Each cron job creates
tasks with scopes for that particular job, by name.  For example, the
``check-frob`` cron job on that repo would run with
``assume:repo:hg.mozilla.org/projects/sequoia:cron:check-frob``.

.. important::

    The individual cron scopes are a useful check to ensure that a job is not
    accidentally doing something it should not, but cannot actually *prevent* a
    job from using any of the scopes afforded to the cron task itself (the
    ``..cron:*`` scope).  This is simply because the cron task runs arbitrary
    code from the repo, and that code can be easily modified to create tasks
    with any scopes that it possesses.