feat(infra): Add base_os_version to support parallel builds (#14128)

## What this PR does
This PR resolves a critical GLIBC mismatch error in the parallel
`trial_build` CI pipeline by enabling dynamic selection of the
`base-runner` image. It introduces a hybrid approach to ensure a
project's runtime environment always matches its build environment.

## Why this PR is important
Currently, fuzzers built on a newer OS (e.g., Ubuntu 24.04) during
parallel CI runs fail during the `check_build` step because they are
always tested against an older, hardcoded `base-runner:latest` image
(Ubuntu 20.04). This change is crucial to unblock parallel builds and
allow projects to use newer base images without breaking the CI.

## How the changes were implemented
* **CI-Level Override:** The `trial_build` function now passes a
`--base-image-tag` to `helper.py`. This tag corresponds to the OS
version of the build job (e.g., `ubuntu-24-04`), ensuring the
`check_build` step uses the correct runner image.
* **Project-Level Configuration:** A new `base_os_version` field is
introduced in `project.yaml`. This allows developers to specify a base
OS for local runs of `run_fuzzer`, `reproduce`, etc., making local
testing consistent with CI.
* **Centralized Image Logic:** All commands in `helper.py` that use a
runner image now call a refactored `_get_base_runner_image` function.
This function implements the priority system: `--base-image-tag` >
`base_os_version` > `legacy` default.
* **New Consistency Check:** A new GitHub Actions workflow
(`check_base_os.yml`) is added. It triggers on pull requests modifying
`projects/` and verifies that the `base_os_version` in `project.yaml`
matches the `FROM` tag in the project's `Dockerfile`, preventing
configuration errors.
* **Bug Fix:** The logic for selecting debug images (`reproduce
--valgrind`) was also corrected as part of the refactoring.

## How to test
1. The primary validation is through the CI itself. A `trial_build` for
a project using a newer `Dockerfile` (e.g., based on Ubuntu 24.04)
should now pass the `check_build` step.
2. Locally, a developer can add `base_os_version: ubuntu-24-04` to a
`project.yaml` (assuming a matching `Dockerfile`) and confirm that
`python3 infra/helper.py run_fuzzer <project> <fuzzer>` uses the
`gcr.io/oss-fuzz-base/base-runner:ubuntu-24-04` image.

## Is it a breaking change?
No. The default behavior is unchanged. All existing projects without the
new `base_os_version` field will continue to use the `legacy`
(`:latest`) runner image, making the change fully backward-compatible.

## Related Task
*   **Taskflow:** [b/441792502](b/441792502)

Author: hunsche

.github/workflows/check_base_os.yml

@@ -0,0 +1,61 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+################################################################################
+
+name: 'Check Base OS Consistency'
+
+on:
+  pull_request:
+    paths:
+      - 'projects/**'
+
+jobs:
+  check-consistency:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history to compare with main
+
+      - name: Get changed project directories
+        id: changed-projects
+        run: |
+          # Get the list of changed files compared to the target branch
+          # and filter for unique directories under 'projects/'.
+          CHANGED_DIRS=$(git diff --name-only ${{ github.base_ref }} ${{ github.head_ref }} | \
+            grep '^projects/' | \
+            xargs -n 1 dirname | \
+            sort -u)
+          echo "changed_dirs=${CHANGED_DIRS}" >> $GITHUB_OUTPUT
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: pip install PyYAML
+
+      - name: Check each modified project
+        if: steps.changed-projects.outputs.changed_dirs != ''
+        run: |
+          EXIT_CODE=0
+          for project_dir in ${{ steps.changed-projects.outputs.changed_dirs }};
+          do
+            echo "--- Checking ${project_dir} ---"
+            python3 infra/ci/check_base_os.py "${project_dir}" || EXIT_CODE=$?
+          done
+          exit $EXIT_CODE

infra/build/functions/build_lib.py

@@ -685,12 +685,24 @@ def get_gcb_url(build_id, cloud_project='oss-fuzz'):
       f'{build_id}?project={cloud_project}')
 
 
-def get_runner_image_name(test_image_suffix):
-  """Returns the runner image that should be used. Returns the testing image if
-  |test_image_suffix|."""
+def get_runner_image_name(test_image_suffix, base_image_tag=None):
+  """Returns the runner image that should be used.
+
+  Returns the testing image if |test_image_suffix|.
+  """
   image = f'gcr.io/{BASE_IMAGES_PROJECT}/base-runner'
+
+  # For trial builds, the version is embedded in the suffix.
   if test_image_suffix:
     image += '-' + test_image_suffix
+    return image
+
+  # For local/manual runs, the version is passed as a tag.
+  # Only add a tag if it's specified and not 'legacy', as 'legacy' implies
+  # 'latest', which is the default behavior.
+  if base_image_tag and base_image_tag != 'legacy':
+    image += ':' + base_image_tag
+
   return image
 
 

infra/build/functions/build_project.py

@@ -73,6 +73,7 @@
 class Config:
   testing: bool = False
   test_image_suffix: Optional[str] = None
+  base_image_tag: Optional[str] = None
   repo: Optional[str] = DEFAULT_OSS_FUZZ_REPO
   branch: Optional[str] = None
   parallel: bool = False
@@ -453,8 +454,10 @@ def get_build_steps_for_project(project,
               f'--architecture {build.architecture} {project.name}\\n' +
               '*' * 80)
           # Test fuzz targets.
+          runner_image_name = build_lib.get_runner_image_name(
+              config.test_image_suffix, config.base_image_tag)
           test_step = {
-              'name': build_lib.get_runner_image_name(config.test_image_suffix),
+              'name': runner_image_name,
               'env': env,
               'args': [
                   'bash', '-c',

infra/build/functions/trial_build.py

@@ -321,6 +321,7 @@ def _do_test_builds(args, test_image_suffix, end_time, version_tag):
 
     config = build_project.Config(testing=True,
                                   test_image_suffix=test_image_suffix,
+                                  base_image_tag=version_tag,
                                   repo=args.repo,
                                   branch=args.branch,
                                   parallel=False,
@@ -432,7 +433,7 @@ def _do_build_type_builds(args, config, credentials, build_type, projects):
           credentials,
           build_type.type_name,
           extra_tags=tags,
-          timeout=PROJECT_BUILD_TIMEOUT))
+          timeout=PROJECT_BUILD_TIMEOUT))['id']
       time.sleep(1)  # Avoid going over 75 requests per second limit.
     except Exception as error:  # pylint: disable=broad-except
       # Handle flake.

infra/build/functions/trial_build_test.py

@@ -73,7 +73,7 @@ def test_build_steps_correct(self, mock_gcb_build_and_push_images,
     del mock_wait_on_builds
     self.maxDiff = None  # pylint: disable=invalid-name
     build_id = 1
-    mock_run_build.return_value = build_id
+    mock_run_build.return_value = {'id': build_id}
     branch_name = 'mybranch'
     project = 'skcms'
     args = [

infra/ci/check_base_os.py

@@ -0,0 +1,111 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+################################################################################
+"""
+A CI script to ensure that the base OS version specified in a project's
+project.yaml file matches the FROM line in its Dockerfile.
+"""
+
+import os
+import sys
+import yaml
+
+# Defines the base OS versions that are currently supported for use in project.yaml.
+# For now, only 'legacy' is permitted. This list will be expanded as new
+# base images are rolled out.
+SUPPORTED_VERSIONS = [
+    'legacy',
+    # 'ubuntu-20-04',
+    # 'ubuntu-24-04',
+]
+
+# A map from the base_os_version in project.yaml to the expected Dockerfile
+# FROM tag.
+BASE_OS_TO_DOCKER_TAG = {
+    'legacy': 'latest',
+    'ubuntu-20-04': 'ubuntu-20-04',
+    'ubuntu-24-04': 'ubuntu-24-04',
+}
+
+
+def main():
+  """Checks the Dockerfile FROM tag against the project's base_os_version."""
+  if len(sys.argv) < 2:
+    print(f'Usage: {sys.argv[0]} <project_path>', file=sys.stderr)
+    return 1
+
+  project_path = sys.argv[1]
+  project_yaml_path = os.path.join(project_path, 'project.yaml')
+  dockerfile_path = os.path.join(project_path, 'Dockerfile')
+
+  # 1. Get the base_os_version from project.yaml, defaulting to 'legacy'.
+  base_os_version = 'legacy'
+  if os.path.exists(project_yaml_path):
+    with open(project_yaml_path) as f:
+      config = yaml.safe_load(f)
+      if config and 'base_os_version' in config:
+        base_os_version = config['base_os_version']
+
+  # 2. Validate that the version is currently supported.
+  if base_os_version not in SUPPORTED_VERSIONS:
+    print(
+        f'Error: base_os_version "{base_os_version}" is not yet supported. '
+        f'The currently supported versions are: "{", ".join(SUPPORTED_VERSIONS)}"',
+        file=sys.stderr)
+    return 1
+
+  # 3. Get the expected Dockerfile tag from our mapping.
+  expected_tag = BASE_OS_TO_DOCKER_TAG[base_os_version]
+
+  # 4. Read the Dockerfile and find the tag in the FROM line.
+  if not os.path.exists(dockerfile_path):
+    print(f'Error: Dockerfile not found at {dockerfile_path}', file=sys.stderr)
+    return 1
+
+  dockerfile_tag = ''
+  with open(dockerfile_path) as f:
+    for line in f:
+      if line.strip().startswith('FROM'):
+        try:
+          if ':' not in line:
+            print(
+                f'Error: Malformed FROM line in Dockerfile (missing tag): {line.strip()}',
+                file=sys.stderr)
+            return 1
+          dockerfile_tag = line.split(':')[1].strip()
+        except IndexError:
+          print(f'Error: Could not parse tag from Dockerfile FROM line: {line}',
+                file=sys.stderr)
+          return 1
+        break
+
+  # 5. Compare and report.
+  if dockerfile_tag != expected_tag:
+    print(
+        f'Error: Mismatch found in {project_path}.\n'
+        f'  - project.yaml (base_os_version): "{base_os_version}" (expects Dockerfile tag "{expected_tag}")\n'
+        f'  - Dockerfile FROM tag: "{dockerfile_tag}"\n'
+        f'Please align the Dockerfile\'s FROM line to use the tag "{expected_tag}".',
+        file=sys.stderr)
+    return 1
+
+  print(
+      f'Success: {project_path} is consistent (base_os_version: "{base_os_version}", Dockerfile tag: "{dockerfile_tag}").'
+  )
+  return 0
+
+
+if __name__ == '__main__':
+  sys.exit(main())