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