taskcluster/docs/attributes.rst

   1 ===============
   2 Task Attributes
   3 ===============
   4
   5 Tasks can be filtered, for example to support "try" pushes which only perform a
   6 subset of the task graph or to link dependent tasks.  This filtering is the
   7 difference between a full task graph and a target task graph.
   8
   9 Filtering takes place on the basis of attributes.  Each task has a dictionary
  10 of attributes and filters over those attributes can be expressed in Python.  A
  11 task may not have a value for every attribute.
  12
  13 The attributes, and acceptable values, are defined here.  In general, attribute
  14 names and values are the short, lower-case form, with underscores.
  15
  16 kind
  17 ====
  18
  19 A task's ``kind`` attribute gives the name of the kind that generated it, e.g.,
  20 ``build`` or ``spidermonkey``.
  21
  22 run_on_projects
  23 ===============
  24
  25 The projects where this task should be in the target task set.  This is how
  26 requirements like "only run this on autoland" get implemented.
  27
  28 .. note::
  29
  30     Please use this configuration. Running a job for all projects can quickly add up
  31     in term of cost while not providing any value for some projects.
  32
  33 `run-on-projects` can use either aliases or project names.
  34
  35 These are the aliases:
  36
  37  * `integration` -- integration repository (autoland)
  38  * `trunk` -- integration repository plus mozilla-central
  39  * `release` -- release repositories (beta, release, esr) including mozilla-central
  40  * `all` -- everywhere (the default)
  41
  42 Project names are the repositories.  They can be:
  43
  44 * `autoland`
  45 * `mozilla-central`
  46 * `mozilla-beta`
  47 * `mozilla-release`
  48 * `mozilla-esr115`
  49 * ... A partial list can be found in taskcluster/gecko_taskgraph/util/attributes.py
  50
  51 For try, this attribute applies only if ``-p all`` is specified.  All jobs can
  52 be specified by name regardless of ``run_on_projects``.
  53
  54 If ``run_on_projects`` is set to an empty list, then the task will not run
  55 anywhere, unless its build platform is specified explicitly in try syntax.
  56
  57
  58 .. note::
  59
  60     As `try` pushes don't use filter_for_projects by design, there isn't a way
  61     to define that a task will run on `try`.
  62
  63
  64 .. note::
  65
  66     A given task `[taskA]` may not respect `run-on-projects` if there another task
  67     `[taskB]` which is scheduled to run (such as via run-on-projects) which depends it
  68     `[taskA]`. Because by nature of `TaskB` running we must run `TaskA`.
  69
  70     See `bug 1640603 <https://bugzilla.mozilla.org/show_bug.cgi?id=1640603#c5>`_ as example.
  71
  72 run_on_hg_branches
  73 ==================
  74
  75 On a given project, the mercurial branch where this task should be in the target
  76 task set.  This is how requirements like "only run this RELBRANCH" get implemented.
  77 These are either the regular expression of a branch (e.g.: ``GECKOVIEW_\d+_RELBRANCH``)
  78 or the following alias:
  79
  80  * `all` -- everywhere (the default)
  81
  82 Like ``run_on_projects``, the same behavior applies if it is set to an empty list.
  83
  84 task_duplicates
  85 ===============
  86
  87 This is used to indicate that we want multiple copies of the task created.
  88 This feature is used to track down intermittent job failures.
  89
  90 If this value is set to N, the task-creation machinery will create a total of N
  91 copies of the task.  Only the first copy will be included in the taskgraph
  92 output artifacts, although all tasks will be contained in the same taskGroup.
  93
  94 While most attributes are considered read-only, target task methods may alter
  95 this attribute of tasks they include in the target set.
  96
  97 build_platform
  98 ==============
  99
 100 The build platform defines the platform for which the binary was built.  It is
 101 set for both build and test jobs, although test jobs may have a different
 102 ``test_platform``.
 103
 104 build_type
 105 ==========
 106
 107 The type of build being performed.  This is a subdivision of ``build_platform``,
 108 used for different kinds of builds that target the same platform.  Values are
 109
 110  * ``debug``
 111  * ``opt``
 112
 113 test_platform
 114 =============
 115
 116 The test platform defines the platform on which tests are run.  It is only
 117 defined for test jobs and may differ from ``build_platform`` when the same binary
 118 is tested on several platforms (for example, on several versions of Windows).
 119 This applies for both talos and unit tests.
 120
 121 Unlike build_platform, the test platform is represented in a slash-separated
 122 format, e.g., ``linux64/opt``.
 123
 124 unittest_suite
 125 ==============
 126
 127 This is the unit test suite being run in a unit test task.  For example,
 128 ``mochitest`` or ``cppunittest``.
 129
 130 unittest_category
 131 =================
 132
 133 This is the high-level category of test the suite corresponds to. This is
 134 usually the test harness used to run the suite.
 135
 136 unittest_try_name
 137 =================
 138
 139 This is the name used to refer to a unit test via try syntax.  It
 140 may not match ``unittest_suite``.
 141
 142 unittest_variant
 143 ================
 144
 145 The configuration variant the test suite is running with. If set, this usually
 146 means the tests are running with a special pref enabled. These are defined in
 147 ``taskgraph.transforms.test.TEST_VARIANTS``.
 148
 149 talos_try_name
 150 ==============
 151
 152 This is the name used to refer to a talos job via try syntax.
 153
 154 raptor_try_name
 155 ===============
 156
 157 This is the name used to refer to a raptor job via try syntax.
 158
 159 job_try_name
 160 ============
 161
 162 This is the name used to refer to a "job" via try syntax (``-j``).  Note that for
 163 some kinds, ``-j`` also matches against ``build_platform``.
 164
 165 test_chunk
 166 ==========
 167
 168 This is the chunk number of a chunked test suite. Note that this is a string!
 169
 170 test_manifests
 171 ==============
 172
 173 A list of the test manifests that run in this task.
 174
 175 image_name
 176 ==========
 177
 178 For the ``docker_image`` kind, this attribute contains the docker image name.
 179
 180 nightly
 181 =======
 182
 183 Signals whether the task is part of a nightly graph. Useful when filtering
 184 out nightly tasks from full task set at target stage.
 185
 186 shippable
 187 =========
 188 Signals whether the task is considered "shippable", that it should get signed and is ok to
 189 be used for nightlies or releases.
 190
 191 all_locales
 192 ===========
 193
 194 For the ``l10n`` and ``shippable-l10n`` kinds, this attribute contains the list
 195 of relevant locales for the platform.
 196
 197 all_locales_with_changesets
 198 ===========================
 199
 200 Contains a dict of l10n changesets, mapped by locales (same as in ``all_locales``).
 201
 202 l10n_chunk
 203 ==========
 204 For the ``l10n`` and ``shippable-l10n`` kinds, this attribute contains the chunk
 205 number of the job. Note that this is a string!
 206
 207 chunk_locales
 208 =============
 209 For the ``l10n`` and ``shippable-l10n`` kinds, this attribute contains an array of
 210 the individual locales this chunk is responsible for processing.
 211
 212 locale
 213 ======
 214 For jobs that operate on only one locale, we set the attribute ``locale`` to the
 215 specific locale involved. Currently this is only in l10n versions of the
 216 ``beetmover`` and ``balrog`` kinds.
 217
 218 signed
 219 ======
 220 Signals that the output of this task contains signed artifacts.
 221
 222 stub-installer
 223 ==============
 224 Signals to the build system that this build is expected to have a stub installer
 225 present, and informs followon tasks to expect it.
 226
 227 repackage_type
 228 ==============
 229 This is the type of repackage. Can be ``repackage`` or
 230 ``repackage_signing``.
 231
 232 fetch-artifact
 233 ==============
 234
 235 For fetch jobs, this is the path to the artifact for that fetch operation.
 236
 237 fetch-alias
 238 ===========
 239 An alias that can be used instead of the real fetch job name in fetch
 240 stanzas for jobs.
 241
 242 toolchain-artifact
 243 ==================
 244 For toolchain jobs, this is the path to the artifact for that toolchain.
 245
 246 toolchain-alias
 247 ===============
 248 An alias that can be used instead of the real toolchain job name in fetch
 249 stanzas for jobs.
 250
 251 toolchain-env
 252 =============
 253 Extra environment variables that will be set on the worker when fetching this
 254 toolchain.
 255
 256 toolchain-command
 257 =================
 258 An extra attribute used to communicate to the build system bootstrap code the
 259 command used to build the toolchain. This is useful because the commands are
 260 formatted differently depending on the worker type, sometimes inconveniently
 261 to parse afterwards.
 262
 263 always_target
 264 =============
 265
 266 Tasks with this attribute will be included in the ``target_task_graph`` if
 267 ``parameters["tasks_for"]`` is ``hg-push``, regardless of any target task
 268 filtering that occurs. When a task is included in this manner (i.e it otherwise
 269 would have been filtered out), it will be considered for optimization even if
 270 the ``optimize_target_tasks`` parameter is False.
 271
 272 This is meant to be used for tasks which a developer would almost always want to
 273 run. Typically these tasks will be short running and have a high risk of causing
 274 a backout. For example ``lint`` or ``python-unittest`` tasks.
 275
 276 shipping_product
 277 ================
 278 For release promotion jobs, this is the product we are shipping.
 279
 280 shipping_phase
 281 ==============
 282 For release promotion jobs, this is the shipping phase (build, promote, push, ship).
 283 During the build phase, we build and sign shippable builds. During the promote phase,
 284 we generate l10n repacks and push to the candidates directory. During the push phase,
 285 we push to the releases directory. During the ship phase, we update bouncer, push to
 286 Google Play, version bump, mark as shipped in ship-it.
 287
 288 Using the "snowman model", we depend on previous graphs if they're defined. So if we
 289 ask for a ``push`` (the head of the snowman) and point at the body and base, we only
 290 build the head. If we don't point at the body and base, we build the whole snowman
 291 (build, promote, push).
 292
 293 artifact_prefix
 294 ===============
 295 Most taskcluster artifacts are public, so we've hardcoded ``public/build`` in a
 296 lot of places. To support private artifacts, we've moved this to the
 297 ``artifact_prefix`` attribute. It will default to ``public/build`` but will be
 298 overridable per-task.
 299
 300 artifact_map
 301 ===============
 302 For beetmover jobs, this indicates which yaml file should be used to
 303 generate the upstream artifacts and payload instructions to the task.
 304
 305 release_artifacts
 306 =================
 307 A set of artifacts that are candidates for downstream release tasks to operate
 308 on.
 309
 310 batch
 311 =====
 312 Used by `perftest` to indicates that a task can be run as a batch.
 313
 314
 315 enable-full-crashsymbols
 316 ========================
 317 In automation, full crashsymbol package generation is normally disabled.  For
 318 build kinds where the full crashsymbols should be enabled, set this attribute
 319 to True. The full symbol packages will then be generated and uploaded on
 320 release branches and on try.
 321
 322 skip-upload-crashsymbols
 323 ========================
 324 Shippable/nightly builds are normally required to set enable-full-crashsymbols,
 325 but in some limited corner cases (universal builds), that is not wanted, because
 326 the symbols are uploaded independently already.
 327
 328 upload-generated-sources
 329 ========================
 330 generated-sources are normally only uploaded to S3 for shippable/nightly
 331 builds.  This attributes turns that on for other builds such as macosx
 332 before unification.
 333
 334 cron
 335 ====
 336 Indicates that a task is meant to be run via cron tasks, and should not be run
 337 on push.
 338
 339 cached_task
 340 ===========
 341 Some tasks generate artifacts that are cached between pushes. This is a
 342 dictionary with the type and name of the cache, and the unique string used to
 343 identify the current version of the artifacts. See :py:mod:`taskgraph.util.cached_task`.
 344
 345 .. code:: yaml
 346
 347    cached_task:
 348        digest: 66dfc2204600b48d92a049b6a18b83972bb9a92f9504c06608a9c20eb4c9d8ae
 349        name: debian7-base
 350        type: docker-images.v2
 351
 352 eager_indexes
 353 =============
 354 A list of strings of indexes to populate before the task ever completes. Some tasks (e.g. cached tasks) we
 355 want to exist in the index before they even run/complete. Our current use is to allow us to depend on an
 356 unfinished cached task in future pushes. This avoids extra overhead from multiple tasks running, and
 357 can allow us to have our results in just a bit earlier.
 358
 359 required_signoffs
 360 =================
 361 A list of release signoffs that this kind requires, should the release also
 362 require these signoffs. For example, ``mar-signing`` signoffs may be required
 363 by some releases in the future; for any releases that require ``mar-signing``
 364 signoffs, the kinds that also require that signoff are marked with this
 365 attribute.
 366
 367 update-channel
 368 ==============
 369 The update channel the build is configured to use.
 370
 371 mar-channel-id
 372 ==============
 373 The mar-channel-id the build is configured to use.
 374
 375 accepted-mar-channel-ids
 376 ========================
 377 The mar-channel-ids this build will accept updates to. It should usually be the same as
 378 the value mar_channel_id.  If more than one ID is needed, then you should use a
 379 comma separated list of values.
 380
 381 openh264_rev
 382 ============
 383 Only used for openh264 plugin builds, used to signify the revision (and thus inform artifact name) of the given build.
 384
 385 code-review
 386 ===========
 387 If a task set this boolean attribute to `true`, it will be processed by the code
 388 review bot, the task will ran for every new Phabricator diff.
 389 Any supported and detected issue will be automatically reported on the
 390 Phabricator revision.
 391
 392 resource-monitor
 393 ================
 394 If a task set this boolean attribute to `true`, it will collect CPU, memory, and
 395 - if available - Disk and Network IO by running the resource-monitor utility,
 396 provided through fetches.
 397
 398 retrigger
 399 =========
 400 Whether the task can be retriggered, or if it needs to be re-run.
 401
 402 disable-push-apk
 403 ================
 404 Some GeckoView-only Android tasks produce APKs that shouldn't be
 405 pushed to the Google Play Store.  Set this to ``true`` to disable
 406 pushing.
 407
 408 disable-build-signing
 409 =====================
 410 Some GeckoView-only tasks produce APKs, but not APKs that should be
 411 signed.  Set this to ``true`` to disable APK signing.
 412
 413 enable-build-signing
 414 ====================
 415 We enable build-signing for ``shippable``, ``nightly``, and ``enable-build-signing`` tasks.
 416
 417 run-visual-metrics
 418 ==================
 419 If set to true, will run the visual metrics task on the provided
 420 video files.
 421
 422 skip-verify-test-packaging
 423 ==========================
 424 If set to true, this task will not be checked to see that
 425 MOZ_AUTOMATION_PACKAGE_TESTS is set correctly based on whether or not the task
 426 has dependent tests. This should only be used in very unique situations, such
 427 as Windows AArch64 builds that copy test packages between build tasks.
 428
 429 geckodriver
 430 ===========
 431 If non-empty, declares that the (toolchain) task is a `geckodriver`
 432 task that produces a binary that should be signed.
 433
 434 rebuild-on-release
 435 ==================
 436 If true, the digest for this task will also depend on if the branch is a
 437 release branch.  This will cause tasks like toolchains to be rebuilt as they
 438 move from e.g. autoland to mozilla-central.
 439
 440 local-toolchain
 441 ===============
 442 This toolchain is used for local development, so should be built on trunk, even
 443 if it does not have any in-graph consumers.
 444
 445 artifact-build
 446 ==============
 447
 448 This build is an artifact build.
 449
 450 This deliberately excludes builds that are implemented using the artifact build
 451 machinery, but are not primarily intended to short-circuit build time. In
 452 particular the Windows aarch64 builds are not marked this way.
 453
 454 maven_packages
 455 ===============
 456 List of maven packages produced by the build.
 457
 458 supports-artifact-builds
 459 ========================
 460
 461 If false, the task requires a compiled build and will not work with artifact builds.
 462
 463 primary-kind-dependency
 464 =======================
 465
 466 For tasks that were derived from a group of dependencies, this attribute
 467 denotes which dependent kind is the `primary one`_.
 468
 469 Typically this is set by the ``taskgraph.transforms.from_deps`` transforms.
 470
 471 snap_test_type
 472 ==============
 473
 474 For Snap tests tasks, used to disambiguate task label
 475
 476 .. _primary one: https://taskcluster-taskgraph.readthedocs.io/en/latest/reference/transforms/from_deps.html#primary-kind
 477
 478 build-type
 479 ==========
 480 For android builds, the type of build: typically debug, nightly, beta, release.
 481
 482 component
 483 =========
 484 For android-components builds, the name of the component.
 485
 486 apks
 487 ====
 488 For android apk build tasks, the list of apk artifact names.
 489
 490 aab
 491 ===
 492 For android aab build tasks, the aab artifact names.
 493
 494 release-type
 495 ============
 496 For android builds, the type of release: typically debug, nightly, beta, release.
 497
 498 shipping-product
 499 ================
 500 For android tasks, the shipping product: Fenix, Focus, or an android-component name.
 501
 502 artifacts
 503 =========
 504 For android-components tasks, a dictionary mapping extensions to artifact names.
 505
 506 is_final_chunked_task
 507 =====================
 508 Used by taskcluster.android_taskgraph.transforms.chunk to mark the last task in a chunk group.
 509
 510 legacy
 511 ======
 512 Used by Fenix UI tests to select UI tests on legacy Android devices and API levels.
 513
 514 nightly-test
 515 ============
 516 Used by Fenix browsertime tests to mark the task as part of the nightly-test graph.
 517
 518 screenshots
 519 ===========
 520 Used by Fenix UI tests to mark the task as part of the screenshots graph.
 521
 522 abi
 523 ===
 524 Used by android browsertime tasks to track the abi of the product under test.
 525
 526 apk
 527 ===
 528 Used by android browsertime tasks to track the path to the apk of the product under test.