{"id":5512,"library":"taskcluster-taskgraph","title":"Taskcluster Taskgraph Generator","description":"Taskgraph is a Python library designed to generate complex dependency graphs for the Taskcluster CI service. It serves as the recommended approach for configuring CI tasks when projects outgrow simple .taskcluster.yml configurations, powering large-scale CI systems like Firefox's with tens of thousands of tasks. The library is currently at version 20.0.0 and maintains an active release cadence with frequent minor and patch updates.","status":"active","version":"20.0.0","language":"en","source_language":"en","source_url":"https://github.com/taskcluster/taskgraph","tags":["taskcluster","ci/cd","task graphs","automation","workflow","mozilla"],"install":[{"cmd":"pip install taskcluster-taskgraph","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"Common import for defining custom transforms, which modify task definitions.","symbol":"TransformSequence","correct":"from taskgraph.transforms.base import TransformSequence"},{"note":"After 19.1.0, 'Schema' was migrated to msgspec. Use 'LegacySchema' for voluptuous-based schemas or migrate to msgspec.","wrong":"from taskgraph.util.schema import Schema (before 19.x)","symbol":"LegacySchema","correct":"from taskgraph.util.schema import LegacySchema"}],"quickstart":{"code":"# 1. Initialize a new Taskgraph setup in your repository\n# This creates a .taskcluster.yml and a taskcluster/ directory structure.\nmkdir my-repo && cd my-repo\ntaskgraph init\n\n# 2. Generate the task graph locally to see defined tasks\n# This processes your task definitions and transforms.\ntaskgraph full\n\n# To see the full JSON definition of tasks, use the -J/--json flag:\ntaskgraph morphed -J","lang":"bash","description":"The primary interaction with taskcluster-taskgraph is via its command-line interface. The `taskgraph init` command bootstraps a new project with the necessary configuration files and directory structure. You can then use `taskgraph full` to locally generate and view the task graph, and `taskgraph morphed -J` to inspect the final JSON definitions of tasks."},"warnings":[{"fix":"Migrate custom schemas to use the new `msgspec`-based `Schema` or explicitly import `LegacySchema` for continued `voluptuous` compatibility. Refer to the migration guide for detailed steps.","message":"The schema validation backend was migrated from `voluptuous` to `msgspec` in version 19.1.0. If you have custom schemas or directly interacted with `taskgraph.util.schema.Schema`, your code will require updates.","severity":"breaking","affected_versions":">=19.1.0"},{"fix":"Review `run-task` scripts and worker configurations to ensure proper cleanup if required. Update paths for `root_dir`, `config.yml`, and `taskcluster/ci` (now `taskcluster/kinds`) in custom logic or configuration.","message":"In version 18.0.0, support for Mercurial sparse profiles was removed from `run-task`, and `run-task` no longer automatically cleans up the `fetches` directory. Additionally, the default root directory for configuration changed, and `config.yml` and the `ci` directory were renamed/moved.","severity":"breaking","affected_versions":">=18.0.0"},{"fix":"Remove `--tag` from `taskgraph build-image` commands and handle image tagging manually. Add `-i` or `--interactive` to `taskgraph load-task` calls where pausing execution is desired.","message":"Version 16.0.0 removed the `--tag` flag from `taskgraph build-image`. Also, `taskgraph load-task` now requires the `-i/--interactive` flag to pause task execution.","severity":"breaking","affected_versions":">=16.0.0"},{"fix":"Ensure your environment uses Python 3.8+. Update all references to the renamed modules and decorators in your transform files and custom logic.","message":"From version 6.x to 7.x, Python 3.8 or higher became a requirement. Several core modules and decorators were renamed (e.g., `taskgraph.transforms.job` to `taskgraph.transforms.run`, `run_job_using` to `run_task_using`).","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Follow the official Taskgraph 'Getting Started' and 'Configuring your Project' documentation to set up the `.taskcluster.yml`, `taskcluster` directory structure, and obtain necessary Taskcluster permissions.","message":"Integrating Taskgraph into a CI system requires a 'Decision Task' defined in a `.taskcluster.yml` file, a `taskcluster` directory with kind definitions and transforms, and proper permissions (scopes) configured within your Taskcluster deployment, potentially including a GitHub App integration.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}