taskcluster/docs/parameters.rst

   1 ==========
   2 Parameters
   3 ==========
   4
   5 Task-graph generation takes a collection of parameters as input, in the form of
   6 a JSON or YAML file.
   7
   8 During decision-task processing, some of these parameters are supplied on the
   9 command line or by environment variables.  The decision task helpfully produces
  10 a full parameters file as one of its output artifacts.  The other ``mach
  11 taskgraph`` commands can take this file as input.  This can be very helpful
  12 when working on a change to the task graph.
  13
  14 When experimenting with local runs of the task-graph generation, it is always
  15 best to find a recent decision task's ``parameters.yml`` file, and modify that
  16 file if necessary, rather than starting from scratch.  This ensures you have a
  17 complete set of parameters.
  18
  19 The properties of the parameters object are described here, divided roughly by
  20 topic.
  21
  22 Push Information
  23 ----------------
  24
  25 ``backstop``
  26    Whether or not this push is a "backstop" push. That is a push where all
  27    builds and tests should run to ensure regressions aren't accidentally
  28    missed.
  29
  30 ``base_repository``
  31    The repository from which to do an initial clone, utilizing any available
  32    caching.
  33
  34 ``head_repository``
  35    The repository containing the changeset to be built.  This may differ from
  36    ``base_repository`` in cases where ``base_repository`` is likely to be cached
  37    and only a few additional commits are needed from ``head_repository``.
  38
  39 ``base_rev``
  40    The previous revision before ``head_rev`` got merged into. This can be a short revision string.
  41
  42 ``head_rev``
  43    The revision to check out; this can be a short revision string
  44
  45 ``base_ref``
  46    Reference where ``head_rev`` got merged into. It is usually a branch or a tag.
  47
  48 ``head_ref``
  49    For Mercurial repositories, this is the same as ``head_rev``.  For
  50    git repositories, which do not allow pulling explicit revisions, this gives
  51    the symbolic ref containing ``head_rev`` that should be pulled from
  52    ``head_repository``.
  53
  54 ``head_tag``
  55    The tag attached to the revision, if any.
  56
  57 ``files_changed``
  58    The list of all files added or modified by the push.
  59
  60 ``owner``
  61    Email address indicating the person who made the push.  Note that this
  62    value may be forged and *must not* be relied on for authentication.
  63
  64 ``message``
  65    The try syntax in the commit message, if any.
  66
  67 ``pushlog_id``
  68    The ID from the ``hg.mozilla.org`` pushlog
  69
  70 ``pushdate``
  71    The timestamp of the push to the repository that triggered this decision
  72    task.  Expressed as an integer seconds since the UNIX epoch.
  73
  74 ``hg_branch``
  75   The mercurial branch where the revision lives in.
  76
  77 ``build_date``
  78    The timestamp of the build date. Defaults to ``pushdate`` and falls back to present time of
  79    taskgraph invocation. Expressed as an integer seconds since the UNIX epoch.
  80
  81 ``moz_build_date``
  82    A formatted timestamp of ``build_date``. Expressed as a string with the following
  83    format: %Y%m%d%H%M%S
  84
  85 ``repository_type``
  86    The type of repository, either ``hg`` or ``git``.
  87
  88 ``tasks_for``
  89    The ``tasks_for`` value used to generate the decision task.
  90
  91 Tree Information
  92 ----------------
  93
  94 ``project``
  95    Another name for what may otherwise be called tree or branch or
  96    repository.  This is the unqualified name, such as ``mozilla-central`` or
  97    ``cedar``.
  98
  99 ``level``
 100    The `SCM level
 101    <https://www.mozilla.org/en-US/about/governance/policies/commit/access-policy/>`_
 102    associated with this tree.  This dictates the names of resources used in the
 103    generated tasks, and those tasks will fail if it is incorrect.
 104
 105 Try Configuration
 106 -----------------
 107
 108 ``try_mode``
 109    The mode in which a try push is operating.  This can be one of:
 110
 111     * ``"try_task_config"`` - Used to configure the taskgraph.
 112     * ``"try_option_syntax"`` - Used when pushing to try with legacy try syntax.
 113     * ``"try_auto"`` - Used to make try pushes behave more like a push on ``autoland``.
 114     * ``"try_select"`` - Used by ``mach try`` to build a list of tasks locally.
 115     * ``None`` - Not a try push or ``mach try release``.
 116
 117 ``try_options``
 118     The arguments given as try syntax (as a dictionary), or ``None`` if
 119     ``try_mode`` is not ``try_option_syntax``.
 120
 121 ``try_task_config``
 122     The contents of the ``try_task_config.json`` file, or ``{}`` if
 123     ``try_mode`` is not ``try_task_config``.
 124
 125 Test Configuration
 126 ------------------
 127
 128 ``test_manifest_loader``
 129    The test manifest loader to use as defined in ``taskgraph.util.chunking.manifest_loaders``.
 130
 131 Target Set
 132 ----------
 133
 134 The "target set" is the set of task labels which must be included in a task
 135 graph.  The task graph generation process will include any tasks required by
 136 those in the target set, recursively.  In a decision task, this set can be
 137 specified programmatically using one of a variety of methods (e.g., parsing try
 138 syntax or reading a project-specific configuration file).
 139
 140 ``enable_always_target``
 141    Can either be a boolean or a list of kinds.
 142
 143    When ``True``, any task with the ``always_target`` attribute will be included
 144    in the ``target_task_graph`` regardless of whether they were filtered out by
 145    the ``target_tasks_method`` or not. Because they are not part of the
 146    ``target_set``, they will still be eligible for optimization when the
 147    ``optimize_target_tasks`` parameter is ``False``.
 148
 149    When specified as a list of kinds, only tasks with a matching kind will be
 150    eligible for addition to the graph.
 151
 152 ``filters``
 153    List of filter functions (from ``taskcluster/gecko_taskgraph/filter_tasks.py``) to
 154    apply. This is usually defined internally, as filters are typically
 155    global.
 156
 157 ``target_tasks_method``
 158    The method to use to determine the target task set.  This is the suffix of
 159    one of the functions in ``taskcluster/gecko_taskgraph/target_tasks.py``.
 160
 161 ``release_history``
 162    History of recent releases by platform and locale, used when generating
 163    partial updates for nightly releases.
 164    Suitable contents can be generated with ``mach release-history``,
 165    which will print to the console by default.
 166
 167 Optimization
 168 ------------
 169
 170 ``optimize_strategies``
 171    A python path of the form ``<module>:<object>`` containing a dictionary of
 172    optimization strategies to use, overwriting the defaults.
 173
 174 ``optimize_target_tasks``
 175    If true, then target tasks are eligible for optimization.
 176
 177 ``do_not_optimize``
 178    Specify tasks to not optimize out of the graph. This is a list of labels.
 179    Any tasks in the graph matching one of the labels will not be optimized out
 180    of the graph.
 181
 182 ``existing_tasks``
 183    Specify tasks to optimize out of the graph. This is a dictionary of label to taskId.
 184    Any tasks in the graph matching one of the labels will use the previously-run
 185    taskId rather than submitting a new task.
 186
 187 Release Promotion
 188 -----------------
 189
 190 ``build_number``
 191    Specify the release promotion build number.
 192
 193 ``version``
 194    Specify the version for release tasks.
 195
 196 ``app_version``
 197    Specify the application version for release tasks. For releases, this is often a less specific version number than ``version``.
 198
 199 ``next_version``
 200    Specify the next version for version bump tasks.
 201
 202 ``release_type``
 203    The type of release being promoted. One of "nightly", "beta", "esr115", "release-rc", or "release".
 204
 205 ``release_eta``
 206    The time and date when a release is scheduled to live. This value is passed to Balrog.
 207
 208 ``release_enable_partner_repack``
 209    Boolean which controls repacking vanilla Firefox builds for partners.
 210
 211 ``release_enable_partner_attribution``
 212    Boolean which controls adding attribution to vanilla Firefox builds for partners.
 213
 214 ``release_enable_emefree``
 215    Boolean which controls repacking vanilla Firefox builds into EME-free builds.
 216
 217 ``release_partners``
 218    List of partners to repack or attribute if a subset of the whole config. A null value defaults to all.
 219
 220 ``release_partner_config``
 221    Configuration for partner repacks & attribution, as well as EME-free repacks.
 222
 223 ``release_partner_build_number``
 224    The build number for partner repacks. We sometimes have multiple partner build numbers per release build number; this parameter lets us bump them independently. Defaults to 1.
 225
 226 ``release_product``
 227    The product that is being released.
 228
 229 ``required_signoffs``
 230    A list of signoffs that are required for this release promotion flavor. If specified, and if the corresponding `signoff_urls` url isn't specified, tasks that require these signoffs will not be scheduled.
 231
 232 ``signoff_urls``
 233    A dictionary of signoff keys to url values. These are the urls marking the corresponding ``required_signoffs`` as signed off.
 234
 235
 236 Repository Merge Day
 237 --------------------
 238
 239 ``merge_config``
 240    Merge config describes the repository merge behaviour, using an alias to cover which set of file replacements and version increments are required, along with overrides for the source and target repository URIs.
 241
 242 ``source_repo``
 243    The clone/push URI of the source repository, such as https://hg.mozilla.org/mozilla-central
 244
 245 ``target_repo``
 246    The clone/push URI of the target repository, such as https://hg.mozilla.org/releases/mozilla-beta
 247
 248 ``source_branch``
 249    The firefoxtree alias of the source branch, such as 'central', 'beta'
 250
 251 ``target_branch``
 252    The firefoxtree alias of the target branch, such as 'beta', 'release'
 253
 254 ``force-dry-run``
 255    Don't push any results to target repositories.
 256
 257
 258 Code Review
 259 -----------
 260
 261 ``phabricator_diff``
 262    The code review process needs to know the Phabricator Differential diff that
 263    started the analysis. This parameter must start with `PHID-DIFF-`
 264
 265 Local configuration
 266 -------------------
 267
 268 ``target-kinds``
 269   Generate only the given kinds and their kind-dependencies. This is used for local inspection of the graph
 270   and is not supported at run-time.