diff options
Diffstat (limited to '')
-rw-r--r-- | taskcluster/docs/cron.rst | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/taskcluster/docs/cron.rst b/taskcluster/docs/cron.rst new file mode 100644 index 0000000000..8c1aaed6d1 --- /dev/null +++ b/taskcluster/docs/cron.rst @@ -0,0 +1,102 @@ +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 `the schema <https://hg.mozilla.org/ci/ci-configuration/file/tip/build-decision/src/build_decision/cron/schema.yml>`_ +for details on the format and meaning of this file. + +How It Works +------------ + +The `TaskCluster Hooks Service <https://firefox-ci-tc.services.mozilla.com/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 the `build-decision +<https://hg.mozilla.org/ci/ci-admin/file/default/build-decision>`_ image in a +checkout of the Gecko source tree. + +The task 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} + +.. note:: + + Times are expressed in UTC (Coordinated Universal Time) + + +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. |