taskcluster-taskgraph 19.2.1__tar.gz → 21.0.0__tar.gz

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/.pre-commit-config.yaml

@@ -13,13 +13,13 @@ repos:
         exclude: template
       - id: check-added-large-files
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.14.14
+    rev: v0.15.8
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
       - id: ruff-format
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.9.28
+    rev: 0.11.2
     hooks:
       - id: uv-lock
   - repo: https://github.com/adrienverge/yamllint.git
@@ -28,7 +28,7 @@ repos:
       - id: yamllint
         exclude: template
   - repo: https://github.com/codespell-project/codespell
-    rev: v2.4.1
+    rev: v2.4.2
     hooks:
       - id: codespell
         entry: codespell -I .codespell-ignore-words.txt
@@ -37,7 +37,7 @@ repos:
                 test/test_util_path.py
             )$
   - repo: https://github.com/compilerla/conventional-pre-commit
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
       - id: conventional-pre-commit
         stages: [commit-msg]

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/.taskcluster.yml

@@ -226,6 +226,7 @@ tasks:
                               - $if: 'isPullRequest'
                                 then:
                                     TASKGRAPH_PULL_REQUEST_NUMBER: '${event.pull_request.number}'
+                                    TASKGRAPH_EXTRA_REFS: {$json: ["refs/notes/decision-parameters"]}
                               - $if: 'tasks_for == "action" || tasks_for == "pr-action"'
                                 then:
                                     ACTION_TASK_GROUP_ID: '${action.taskGroupId}'  # taskGroupId of the target task
@@ -251,7 +252,13 @@ tasks:
                           - bash
                           - -cx
                           - $let:
-                                extraArgs: {$if: 'tasks_for == "cron"', then: '${cron.quoted_args}', else: ''}
+                                extraArgs:
+                                    $if: 'tasks_for == "cron"'
+                                    then: '${cron.quoted_args}'
+                                    else:
+                                        $if: 'tasks_for == "github-pull-request"'
+                                        then: '--allow-parameter-override'
+                                        else: ''
                             in:
                                 $if: 'tasks_for == "action" || tasks_for == "pr-action"'
                                 then: >

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Change Log
 
+## [21.0.0] - 2026-04-13
+
+### Added
+
+- Ability for `run-task` to fetch arbitrary extra refs
+- Ability for Decision task to override params via Git notes
+
+### Fixed
+
+- Improved index route verification
+
+### Changed
+
+- BREAKING CHANGE: run-task and decision images now use Debian 13
+
+### Removed
+
+- BREAKING CHANGE: Removed docker-worker features: dind, privileged, loopback-audio
+
+## [20.0.0] - 2026-03-17
+
+### Added
+
+- Support for generic-worker's `hide-cmd-window` feature
+- Ability to process kinds concurrently with threading
+
+### Fixed
+
+- BREAKING CHANGE: Binaries installed as part of `PIP_REQUIREMENTS` by `run-task` now end up in `~/.local/bin`
+- Exception when base revision is the null revision
+- Ability to use `optionally_keyed_by` with underlying dict using msgspec
+
 ## [19.2.1] - 2026-02-19
 
 ### Fixed

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskcluster-taskgraph
-Version: 19.2.1
+Version: 21.0.0
 Summary: Build taskcluster taskgraphs
 Project-URL: Repository, https://github.com/taskcluster/taskgraph
 Project-URL: Issues, https://github.com/taskcluster/taskgraph/issues

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/docs/howto/bootstrap-taskgraph.rst

@@ -101,7 +101,7 @@ in addition to ``taskcluster-taskgraph`` we also want to depend on
    EOF
 
    # This works best if you use the same Python as the one used in the Decision
-   # image (currently 3.11).
+   # image (currently 3.13).
    pip-compile --generate-hashes --output-file requirements.txt requirements.in
 
 .. note::

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/docs/reference/migrations.rst

@@ -3,6 +3,23 @@ Migration Guide
 
 This page can help when migrating Taskgraph across major versions.
 
+20.x -> 21.x
+------------
+
+* If you have tasks using `docker-worker`'s `dind`, `privileged` or `loopback-audio`
+  features, they are no longer supported. Either avoid using these features or migrate
+  to a `generic-worker` pool with D2G payloads enabled.
+* Ensure any task's using the `run-task` or `decision` images work with the new
+  Debian 13 base.
+
+19.x -> 20.x
+------------
+
+* Binaries belonging to packages that get installed by `run-task` as part of
+  the `PIP_REQUIREMENTS` variable, are now installed to `~/.local/bin` instead
+  of `~/.local/lib/<python>/site-packages/bin`. Update any task commands that hardcode
+  the binary path accordingly.
+
 18.x -> 19.x
 ------------
 

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/pyproject.toml

@@ -1,7 +1,7 @@
 ### Project
 [project]
 name = "taskcluster-taskgraph"
-version = "19.2.1"
+version = "21.0.0"
 description = "Build taskcluster taskgraphs"
 readme = "README.rst"
 authors = [

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/decision.py

@@ -264,6 +264,20 @@ def get_decision_parameters(graph_config, options):
     ] == "github-pull-request":
         set_try_config(parameters, task_config_file)
 
+    # load extra parameters from vcs note if able
+    note_ref = "refs/notes/decision-parameters"
+    if options.get("allow_parameter_override") and (
+        note_params := repo.get_note(note_ref)
+    ):
+        try:
+            note_params = json.loads(note_params)
+            logger.info(
+                f"Overriding parameters from {note_ref}:\n{json.dumps(note_params, indent=2)}"
+            )
+            parameters.update(note_params)
+        except ValueError as e:
+            raise Exception(f"Failed to parse {note_ref} as JSON: {e}") from e
+
     result = Parameters(**parameters)
     result.check()
     return result

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/generator.py

@@ -11,6 +11,7 @@ import platform
 from concurrent.futures import (
     FIRST_COMPLETED,
     ProcessPoolExecutor,
+    ThreadPoolExecutor,
     wait,
 )
 from dataclasses import dataclass
@@ -312,15 +313,13 @@ class TaskGraphGenerator:
 
         return all_tasks
 
-    def _load_tasks_parallel(self, kinds, kind_graph, parameters):
+    def _load_tasks_parallel(self, kinds, kind_graph, parameters, executor):
         all_tasks = {}
         futures_to_kind = {}
         futures = set()
         edges = set(kind_graph.edges)
 
-        with ProcessPoolExecutor(
-            mp_context=multiprocessing.get_context("fork")
-        ) as executor:
+        with executor:
 
             def submit_ready_kinds():
                 """Create the next batch of tasks for kinds without dependencies."""
@@ -434,29 +433,50 @@ class TaskGraphGenerator:
         yield "kind_graph", kind_graph
 
         logger.info("Generating full task set")
-        # The short version of the below is: we only support parallel kind
-        # processing on Linux.
+
+        # The next block deals with enabling parallel kind processing, which
+        # currently has different support on different platforms. In summary:
+        # * Parallel kind processing is supported and enabled by default on
+        #   Linux. We use multiple processes by default, but experimental
+        #   support for multiple threads can be enabled instead.
+        # * On other platforms, we have experimental support for parallel
+        #   kind processing with multiple threads.
         #
-        # Current parallel generation relies on multiprocessing, and more
-        # specifically: the "fork" multiprocessing method. This is not supported
-        # at all on Windows (it uses "spawn"). Forking is supported on macOS,
-        # but no longer works reliably in all cases, and our usage of it here
-        # causes crashes. See https://github.com/python/cpython/issues/77906
-        # and http://sealiesoftware.com/blog/archive/2017/6/5/Objective-C_and_fork_in_macOS_1013.html
-        # for more details on that.
-        # Other methods of multiprocessing (both "spawn" and "forkserver")
-        # do not work for our use case, because they cause global variables
-        # to be reinitialized, which are sometimes modified earlier in graph
-        # generation. These issues can theoretically be worked around by
-        # eliminating all reliance on globals as part of task generation, but
-        # is far from a small amount of work in users like Gecko/Firefox.
-        # In the long term, the better path forward is likely to be switching
-        # to threading with a free-threaded python to achieve similar parallel
-        # processing.
-        if platform.system() != "Linux" or os.environ.get("TASKGRAPH_SERIAL"):
-            all_tasks = self._load_tasks_serial(kinds, kind_graph, parameters)
-        else:
-            all_tasks = self._load_tasks_parallel(kinds, kind_graph, parameters)
+        # On all platforms serial kind processing can be enabled by setting
+        # TASKGRAPH_SERIAL in the environment.
+        #
+        # On all platforms, multiple threads can be enabled by setting
+        # TASKGRAPH_USE_THREADS in the environment. Taskgraph must be running
+        # from a free-threaded Python build to see any performance benefits.
+        #
+        # In the long term, the goal is turn enabled parallel kind processing for
+        # all platforms by default using threads, and remove support for multiple
+        # processes altogether.
+        def load_tasks():
+            if platform.system() == "Linux":
+                if os.environ.get("TASKGRAPH_SERIAL"):
+                    return self._load_tasks_serial(kinds, kind_graph, parameters)
+                elif os.environ.get("TASKGRAPH_USE_THREADS"):
+                    executor = ThreadPoolExecutor(max_workers=os.process_cpu_count())
+                else:
+                    executor = ProcessPoolExecutor(
+                        mp_context=multiprocessing.get_context("fork")
+                    )
+                return self._load_tasks_parallel(
+                    kinds, kind_graph, parameters, executor
+                )
+            else:
+                if os.environ.get("TASKGRAPH_SERIAL") or not os.environ.get(
+                    "TASKGRAPH_USE_THREADS"
+                ):
+                    return self._load_tasks_serial(kinds, kind_graph, parameters)
+                else:
+                    executor = ThreadPoolExecutor(max_workers=os.process_cpu_count())
+                return self._load_tasks_parallel(
+                    kinds, kind_graph, parameters, executor
+                )
+
+        all_tasks = load_tasks()
 
         full_task_set = TaskGraph(all_tasks, Graph(frozenset(all_tasks), frozenset()))
         yield self.verify("full_task_set", full_task_set, graph_config, parameters)

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/main.py

@@ -933,6 +933,12 @@ def load_task(args):
 @argument(
     "--verbose", "-v", action="store_true", help="include debug-level logging output"
 )
+@argument(
+    "--allow-parameter-override",
+    default=False,
+    action="store_true",
+    help="Allow user to override computed decision task parameters.",
+)
 def decision(options):
     from taskgraph.decision import taskgraph_decision  # noqa: PLC0415
 

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/run-task/run-task

@@ -31,7 +31,7 @@ import time
 import urllib.error
 import urllib.request
 from pathlib import Path
-from typing import Dict, Optional
+from typing import Dict, List, Optional
 
 SECRET_BASEURL_TPL = "{}/secrets/v1/secret/{{}}".format(
     os.environ.get("TASKCLUSTER_PROXY_URL", "http://taskcluster").rstrip("/")
@@ -640,6 +640,7 @@ def git_checkout(
     ssh_key_file: Optional[Path],
     ssh_known_hosts_file: Optional[Path],
     shallow: bool = False,
+    extra_refs: Optional[List[str]] = None,
 ):
     assert head_ref or head_rev
 
@@ -734,6 +735,14 @@ def git_checkout(
         env=env,
     )
 
+    if extra_refs:
+        git_fetch(
+            destination_path,
+            *[f"{ref}:{ref}" for ref in extra_refs],
+            remote=head_repo,
+            env=env,
+        )
+
     args = [
         "git",
         "checkout",
@@ -932,6 +941,8 @@ def collect_vcs_options(args, project, name):
     head_rev = os.environ.get(f"{env_prefix}_HEAD_REV")
     pip_requirements = os.environ.get(f"{env_prefix}_PIP_REQUIREMENTS")
     private_key_secret = os.environ.get(f"{env_prefix}_SSH_SECRET_NAME")
+    if extra_refs := os.environ.get(f"{env_prefix}_EXTRA_REFS"):
+        extra_refs = json.loads(extra_refs)
 
     store_path = os.environ.get("HG_STORE_PATH")
 
@@ -965,6 +976,7 @@ def collect_vcs_options(args, project, name):
         "ssh-secret-name": private_key_secret,
         "pip-requirements": pip_requirements,
         "shallow-clone": shallow_clone,
+        "extra-refs": extra_refs,
     }
 
 
@@ -1014,6 +1026,7 @@ def vcs_checkout_from_args(options):
                 ssh_key_file,
                 ssh_known_hosts_file,
                 shallow=options.get("shallow-clone", False),
+                extra_refs=options.get("extra-refs"),
             )
         elif options["repo-type"] == "hg":
             revision = hg_checkout(
@@ -1044,8 +1057,8 @@ def install_pip_requirements(repositories):
 
     # TODO: Stop using system Python (#381)
     if shutil.which("uv"):
-        user_site_dir = subprocess.run(
-            [sys.executable, "-msite", "--user-site"], capture_output=True, text=True
+        user_base_dir = subprocess.run(
+            [sys.executable, "-msite", "--user-base"], capture_output=True, text=True
         ).stdout.strip()
         cmd = [
             "uv",
@@ -1053,8 +1066,8 @@ def install_pip_requirements(repositories):
             "install",
             "--python",
             sys.executable,
-            "--target",
-            user_site_dir,
+            "--prefix",
+            user_base_dir,
         ]
     else:
         cmd = [sys.executable, "-mpip", "install", "--user", "--break-system-packages"]

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/transforms/task.py

@@ -273,9 +273,6 @@ class DockerWorkerPayloadSchema(Schema, forbid_unknown_fields=False, kw_only=Tru
     taskcluster_proxy: bool
     allow_ptrace: bool
     loopback_video: bool
-    loopback_audio: bool
-    docker_in_docker: bool  # (aka 'dind')
-    privileged: bool
     # environment variables
     env: dict[str, taskref_or_string_msgspec]
     # the maximum time to run, in seconds
@@ -356,9 +353,6 @@ def build_docker_worker_payload(config, task, task_def):
     if worker.get("chain-of-trust"):
         features["chainOfTrust"] = True
 
-    if worker.get("docker-in-docker"):
-        features["dind"] = True
-
     if task.get("needs-sccache"):
         features["taskclusterProxy"] = True
         task_def["scopes"].append(
@@ -375,16 +369,10 @@ def build_docker_worker_payload(config, task, task_def):
 
     capabilities = {}
 
-    for lo in "audio", "video":
-        if worker.get("loopback-" + lo):
-            capitalized = "loopback" + lo.capitalize()
-            devices = capabilities.setdefault("devices", {})
-            devices[capitalized] = True
-            task_def["scopes"].append("docker-worker:capability:device:" + capitalized)
-
-    if worker.get("privileged"):
-        capabilities["privileged"] = True
-        task_def["scopes"].append("docker-worker:capability:privileged")
+    if worker.get("loopback-video"):
+        devices = capabilities.setdefault("devices", {})
+        devices["loopbackVideo"] = True
+        task_def["scopes"].append("docker-worker:capability:device:loopbackVideo")
 
     task_def["payload"] = payload = {
         "image": image,
@@ -569,6 +557,7 @@ class GenericWorkerPayloadSchema(Schema, forbid_unknown_fields=False, kw_only=Tr
     # feature for task to run as current OS user
     run_task_as_current_user: Optional[bool] = None
     taskcluster_proxy: Optional[bool] = None
+    hide_cmd_window: Optional[bool] = None
     # Whether any artifacts are assigned to this worker
     skip_artifacts: Optional[bool] = None
 
@@ -681,6 +670,9 @@ def build_generic_worker_payload(config, task, task_def):
             "generic-worker:run-task-as-current-user:{}".format(task["worker-type"]),
         )
 
+    if worker.get("hide-cmd-window"):
+        features["hideCmdWindow"] = True
+
     if features:
         task_def["payload"]["features"] = features
 
@@ -811,9 +803,6 @@ def set_defaults(config, tasks):
             worker.setdefault("taskcluster-proxy", False)
             worker.setdefault("allow-ptrace", False)
             worker.setdefault("loopback-video", False)
-            worker.setdefault("loopback-audio", False)
-            worker.setdefault("docker-in-docker", False)
-            worker.setdefault("privileged", False)
             worker.setdefault("volumes", [])
             worker.setdefault("env", {})
             if "caches" in worker:

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/util/schema.py

@@ -4,9 +4,9 @@
 
 import pprint
 import re
+import threading
 from collections.abc import Mapping
-from functools import reduce
-from typing import Any, Literal, Optional, Union
+from typing import Annotated, Any, Literal, Optional, Union, get_args, get_origin
 
 import msgspec
 import voluptuous
@@ -14,6 +14,8 @@ import voluptuous
 import taskgraph
 from taskgraph.util.keyed_by import evaluate_keyed_by, iter_dot_path
 
+_schema_creation_lock = threading.RLock()
+
 # Common type definitions that are used across multiple schemas
 TaskPriority = Literal[
     "highest", "very-high", "high", "medium", "low", "very-low", "lowest"
@@ -67,11 +69,37 @@ def validate_schema(schema, obj, msg_prefix):
             raise Exception(f"{msg_prefix}\n{str(exc)}\n{pprint.pformat(obj)}")
 
 
-def UnionTypes(*types):
-    """Use `functools.reduce` to simulate `Union[*allowed_types]` on older
-    Python versions.
-    """
-    return reduce(lambda a, b: Union[a, b], types)
+class OptionallyKeyedBy:
+    """Metadata class for optionally_keyed_by fields in msgspec schemas."""
+
+    def __init__(self, *fields, wrapped_type):
+        self.fields = {f"by-{field}" for field in fields}
+        self.wrapped_type = wrapped_type
+
+    def uses_keyed_by(self, obj) -> bool:
+        if not isinstance(obj, dict) or len(obj) != 1:
+            return False
+
+        key = list(obj)[0]
+        if key not in self.fields:
+            return False
+
+        return True
+
+    def validate(self, obj) -> None:
+        if not self.uses_keyed_by(obj):
+            # Not using keyed by, validate directly against wrapped type
+            msgspec.convert(obj, self.wrapped_type)
+            return
+
+        # First validate the outer keyed-by dict
+        msgspec.convert(obj, dict[str, dict])
+
+        # Next validate each inner value. We call self.validate recursively to
+        # support nested `by-*` keys.
+        keyed_by_dict = list(obj.values())[0]
+        for value in keyed_by_dict.values():
+            self.validate(value)
 
 
 def optionally_keyed_by(*arguments, use_msgspec=False):
@@ -83,13 +111,15 @@ def optionally_keyed_by(*arguments, use_msgspec=False):
         use_msgspec: If True, return msgspec type hints; if False, return voluptuous validator
     """
     if use_msgspec:
-        # msgspec implementation - return type hints
+        # msgspec implementation - use Annotated[Any, OptionallyKeyedBy]
         _type = arguments[-1]
         if _type is object:
             return object
         fields = arguments[:-1]
-        bykeys = [Literal[f"by-{field}"] for field in fields]
-        return Union[_type, dict[UnionTypes(*bykeys), dict[str, Any]]]
+        wrapper = OptionallyKeyedBy(*fields, wrapped_type=_type)
+        # Annotating Any allows msgspec to accept any value without validation.
+        # The actual validation then happens in Schema.__post_init__
+        return Annotated[Any, wrapper]
     else:
         # voluptuous implementation - return validator function
         schema = arguments[-1]
@@ -253,28 +283,36 @@ class LegacySchema(voluptuous.Schema):
     """
     Operates identically to voluptuous.Schema, but applying some taskgraph-specific checks
     in the process.
+
+    voluptuous.Schema's `_compile` method is thread-unsafe. Any usage (whether direct or
+    indirect) of it must be protected by a lock.
     """
 
     def __init__(self, *args, check=True, **kwargs):
-        super().__init__(*args, **kwargs)
+        with _schema_creation_lock:
+            # this constructor may call `_compile`
+            super().__init__(*args, **kwargs)
 
-        self.check = check
-        if not taskgraph.fast and self.check:
-            check_schema(self)
+            self.check = check
+            if not taskgraph.fast and self.check:
+                check_schema(self)
 
     def extend(self, *args, **kwargs):
-        schema = super().extend(*args, **kwargs)
+        with _schema_creation_lock:
+            # `extend` may create a new Schema object, which may call `_compile`
+            schema = super().extend(*args, **kwargs)
 
-        if self.check:
-            check_schema(schema)
-        # We want twice extend schema to be checked too.
-        schema.__class__ = LegacySchema
-        return schema
+            if self.check:
+                check_schema(schema)
+            # We want twice extend schema to be checked too.
+            schema.__class__ = LegacySchema
+            return schema
 
     def _compile(self, schema):
-        if taskgraph.fast:
-            return
-        return super()._compile(schema)
+        with _schema_creation_lock:
+            if taskgraph.fast:
+                return
+            return super()._compile(schema)
 
     def __getitem__(self, item):
         return self.schema[item]  # type: ignore
@@ -307,6 +345,31 @@ class Schema(
             foo: str
     """
 
+    def __post_init__(self):
+        if taskgraph.fast:
+            return
+
+        # Validate fields that use optionally_keyed_by. We need to validate this
+        # manually because msgspec doesn't support union types with multiple
+        # dicts. Any fields that use `optionally_keyed_by("foo", dict)` would
+        # otherwise raise an exception.
+        for field_name, field_type in self.__class__.__annotations__.items():
+            origin = get_origin(field_type)
+            args = get_args(field_type)
+
+            if (
+                origin is not Annotated
+                or len(args) < 2
+                or not isinstance(args[1], OptionallyKeyedBy)
+            ):
+                # Not using `optionally_keyed_by`
+                continue
+
+            keyed_by = args[1]
+            obj = getattr(self, field_name)
+
+            keyed_by.validate(obj)
+
     @classmethod
     def validate(cls, data):
         """Validate data against this schema."""
@@ -314,7 +377,7 @@ class Schema(
             return data
 
         try:
-            return msgspec.convert(data, cls)
+            msgspec.convert(data, cls)
         except (msgspec.ValidationError, msgspec.DecodeError) as e:
             raise msgspec.ValidationError(str(e))
 

{taskcluster_taskgraph-19.2.1 → taskcluster_taskgraph-21.0.0}/src/taskgraph/util/vcs.py

@@ -215,6 +215,14 @@ class Repository(ABC):
         If this function returns an unexpected value, then make sure
         the revision was fetched from the remote repository."""
 
+    def get_note(self, note: str, revision: Optional[str] = None) -> Optional[str]:
+        """Read a note attached to the given revision (defaults to HEAD).
+
+        Returns the note content as a string, or ``None`` if no note exists.
+        Only supported by Git; returns ``None`` for all other VCS types.
+        """
+        return None
+
 
 class HgRepository(Repository):
     @property
@@ -505,6 +513,11 @@ class GitRepository(Repository):
                 cmd.append("--cached")
             elif mode == "all":
                 cmd.append("HEAD")
+        elif base == self.NULL_REVISION:
+            # When base is NULL_REVISION (e.g new branches on Github), diff
+            # from the empty tree to show all files present at rev. Use Git's
+            # well-known empty tree hash.
+            cmd = ["diff", "4b825dc642cb6eb9a060e54bf8d69288fbee4904", rev]
         elif self.is_shallow:
             # In shallow clones, `git log` won't have the history necessary to
             # determine the files changed. Using `git diff` finds the
@@ -581,6 +594,18 @@ class GitRepository(Repository):
                 return False
             raise
 
+    def get_note(self, note: str, revision: Optional[str] = None) -> Optional[str]:
+        if not note.startswith("refs/notes/"):
+            note = f"refs/notes/{note}"
+
+        revision = revision or "HEAD"
+        try:
+            return self.run("notes", f"--ref={note}", "show", revision).strip()
+        except subprocess.CalledProcessError as e:
+            if e.returncode == 1:
+                return None
+            raise
+
 
 def get_repository(path: str):
     """Get a repository object for the repository at `path`.