taskcluster/docs/cron.rst

   1 Periodic Taskgraphs
   2 ===================
   3
   4 The cron functionality allows in-tree scheduling of task graphs that run
   5 periodically, instead of on a push.
   6
   7 Cron.yml
   8 --------
   9
  10 In the root of the Gecko directory, you will find `.cron.yml`.  This defines
  11 the periodic tasks ("cron jobs") run for Gecko.  Each specifies a name, what to
  12 do, and some parameters to determine when the cron job should occur.
  13
  14 See `the schema <https://hg.mozilla.org/ci/ci-configuration/file/tip/build-decision/src/build_decision/cron/schema.yml>`_
  15 for details on the format and meaning of this file.
  16
  17 How It Works
  18 ------------
  19
  20 The `TaskCluster Hooks Service <https://firefox-ci-tc.services.mozilla.com/hooks>`_
  21 has a hook configured for each repository supporting periodic task graphs.  The
  22 hook runs every 15 minutes, and the resulting task is referred to as a "cron task".
  23 That cron task runs the `build-decision
  24 <https://hg.mozilla.org/ci/ci-admin/file/default/build-decision>`_ image in a
  25 checkout of the Gecko source tree.
  26
  27 The task reads ``.cron.yml``, then consults the current time (actually the time
  28 the cron task was created, rounded down to the nearest 15 minutes) and creates
  29 tasks for any cron jobs scheduled at that time.
  30
  31 Each cron job in ``.cron.yml`` specifies a ``job.type``, corresponding to a
  32 function responsible for creating TaskCluster tasks when the job runs.
  33
  34 Describing Time
  35 ---------------
  36
  37 This cron implementation understands the following directives when
  38 describing when to run:
  39
  40 * ``minute``: The minute in which to run, must be in 15 minute increments (see above)
  41 * ``hour``: The hour of the day in which to run, in 24 hour time.
  42 * ``day``: The day of the month as an integer, such as `1`, `16`. Be cautious above `28`, remember February.
  43 * ``weekday``: The day of the week, `Monday`, `Tuesday`, etc. Full length ISO compliant words.
  44
  45 Setting both 'day' and 'weekday' will result in a cron job that won't run very often,
  46 and so is undesirable.
  47
  48 *Examples*
  49
  50 .. code-block:: yaml
  51
  52     # Never
  53     when: []
  54
  55     # 4 AM and 4 PM, on the hour, every day.
  56     when:
  57         - {hour: 16, minute: 0}
  58         - {hour: 4, minute: 0}
  59
  60     # The same as above, on a single line
  61     when: [{hour: 16, minute: 0}, {hour: 4, minute: 0}]
  62
  63     # 4 AM on the second day of every month.
  64     when:
  65         - {day: 2, hour: 4, minute: 0}
  66
  67     # Mondays and Thursdays at 10 AM
  68     when:
  69         - {weekday: 'Monday', hour: 10, minute: 0}
  70         - {weekday: 'Thursday', hour: 10, minute: 0}
  71
  72 .. note::
  73
  74    Times are expressed in UTC (Coordinated Universal Time)
  75
  76
  77 Decision Tasks
  78 ..............
  79
  80 For ``job.type`` "decision-task", tasks are created based on
  81 ``.taskcluster.yml`` just like the decision tasks that result from a push to a
  82 repository.  They run with a distinct ``taskGroupId``, and are free to create
  83 additional tasks comprising a task graph.
  84
  85 Scopes
  86 ------
  87
  88 The cron task runs with the sum of all cron job scopes for the given repo.  For
  89 example, for the "sequoia" project, the scope would be
  90 ``assume:repo:hg.mozilla.org/projects/sequoia:cron:*``.  Each cron job creates
  91 tasks with scopes for that particular job, by name.  For example, the
  92 ``check-frob`` cron job on that repo would run with
  93 ``assume:repo:hg.mozilla.org/projects/sequoia:cron:check-frob``.
  94
  95 .. important::
  96
  97     The individual cron scopes are a useful check to ensure that a job is not
  98     accidentally doing something it should not, but cannot actually *prevent* a
  99     job from using any of the scopes afforded to the cron task itself (the
 100     ``..cron:*`` scope).  This is simply because the cron task runs arbitrary
 101     code from the repo, and that code can be easily modified to create tasks
 102     with any scopes that it possesses.