Create PyTorch commit pin. (#9654)

This PR creates a PyTorch pin.

**Key Changes:**
- Removed `get-torch-commit` (and, consequently, `torch-commit`
parameters) from GitHub actions files
- Modified the `setup.yml` action by:
    1. Checking out PyTorch/XLA
    2. Retrieving the contents of `.torch_commit`
3. Checking out PyTorch using the contents of the retrieved PyTorch
commit
    4. Moving PyTorch/XLA inside the PyTorch directory
- Add `.torch_commit` file pointing to the commit just before #9651
started happening

This should prevent our CI to break due to some PyTorch breaking changes
as we have experienced recently (e.g. #9653, and #9651). From now on, in
theory, we should only see our CI breaking because of PyTorch changes
whenever we update this pin.

Author: ysiraichi

.github/ci.md

@@ -3,22 +3,22 @@
 PyTorch and PyTorch/XLA use CI to lint, build, and test each PR that is
 submitted. All CI tests should succeed before the PR is merged into master.
 PyTorch CI pins PyTorch/XLA to a specific commit. On the other hand, PyTorch/XLA
-CI pulls PyTorch from master unless a pin is manually provided. This README will
-go through the reasons of these pins, how to pin a PyTorch/XLA PR to an upstream
-PyTorch PR, and how to coordinate a merge for breaking PyTorch changes.
+CI pulls PyTorch from `.torch_commit` unless a pin is manually provided. This
+README will go through the reasons of these pins, how to pin a PyTorch/XLA PR
+to an upstream PyTorch PR, and how to coordinate a merge for breaking PyTorch
+changes.
 
 ## Usage
 
-### Pinning PyTorch PR in PyTorch/XLA PR
+### Temporarily Pinning PyTorch PR in PyTorch/XLA PR
 
 Sometimes a PyTorch/XLA PR needs to be pinned to a specific PyTorch PR to test
-new features, fix breaking changes, etc. Since PyTorch/XLA CI pulls from PyTorch
-master by default, we need to manually provide a PyTorch pin. In a PyTorch/XLA
-PR, PyTorch can be manually pinned by creating a `.torch_pin` file at the root
-of the repository. The `.torch_pin` should have the corresponding PyTorch PR
-number prefixed by "#". Take a look at [example
-here](https://github.com/pytorch/xla/pull/7313). Before the PyTorch/XLA PR gets
-merged, the `.torch_pin` must be deleted.
+new features, fix breaking changes, etc. In a PyTorch/XLA PR, PyTorch can be
+manually pinned by creating a `.torch_pin` file at the root of the repository.
+The `.torch_pin` should have the corresponding PyTorch PR number prefixed by
+"#". Take a look at [example here](https://github.com/pytorch/xla/pull/7313).
+Before the PyTorch/XLA PR gets merged, the `.torch_pin` must be deleted and
+`.torch_commit` updated.
 
 ### Coordinating merges for breaking PyTorch PRs
 
@@ -35,10 +35,11 @@ fail. Steps for fixing and merging such breaking PyTorch change is as following:
    PyTorch PR to pin the PyTorch/XLA to the commit hash created in step 1 by
    updating `pytorch/.github/ci_commit_pins/xla.txt`.
 1. Once CI tests are green on both ends, merge PyTorch PR.
-1. Remove the `.torch_pin` in PyTorch/XLA PR and merge. To be noted, `git commit
-   --amend` should be avoided in this step as PyTorch CI will keep using the
-   commit hash created in step 1 until other PRs update that manually or the
-   nightly buildbot updates that automatically.
+1. Remove the `.torch_pin` in PyTorch/XLA PR and update the `.torch_commit` to
+   the hash of the merged PyTorch PR. To be noted, `git commit --amend` should
+   be avoided in this step as PyTorch CI will keep using the commit hash
+   created in step 1 until other PRs update that manually or the nightly
+   buildbot updates that automatically.
 1. Finally, don't delete your branch until 2 days later. See step 4 for
    explanations.
 
@@ -47,6 +48,18 @@ fail. Steps for fixing and merging such breaking PyTorch change is as following:
 The `build_and_test.yml` workflow runs tests on the TPU in addition to CPU.
 The set of tests run on the TPU is defined in `test/tpu/run_tests.sh`.
 
+## Update the PyTorch Commit Pin
+
+In order to reduce development burden of PyTorch/XLA, starting from #9654, we
+started pinning PyTorch using the `.torch_commit` file. This should reduce the
+number of times a PyTorch PR breaks our most recent commits. However, this also
+requires maintenance, i.e. someone has to keep updating the PyTorch commit so
+as to make sure it's always supporting (almost) the latest PyTorch versions.
+
+Updating the PyTorch commit pin is, theoretically, simple. You just have to run
+`scripts/update_deps.py --pytorch` file, and open a PR. In practice, you may
+encounter a few compilation errors, or even segmentation faults.
+
 ## CI Environment
 
 Before the CI in this repository runs, we build a base dev image. These are the
@@ -152,13 +165,6 @@ good" commit to prevent accidental changes from PyTorch/XLA to break PyTorch CI
 without warning. PyTorch has hundreds of commits each week, and this pin ensures
 that PyTorch/XLA as a downstream package does not cause failures in PyTorch CI.
 
-#### Why does PyTorch/XLA CI pull from PyTorch master?
-
-[PyTorch/XLA CI pulls PyTorch from master][pull-pytorch-master] unless a PyTorch
-pin is manually provided. PyTorch/XLA is a downstream package to PyTorch, and
-pulling from master ensures that PyTorch/XLA will stay up-to-date and works with
-the latest PyTorch changes.
-
 #### TPU CI is broken
 
 If the TPU CI won't run, try to debug using the following steps:

.github/workflows/_build_torch_xla.yml

@@ -6,10 +6,6 @@ on:
                 required: true
                 type: string
                 description: Base image for builds
-            torch-commit:
-                required: true
-                type: string
-                description: torch-commit
             runner:
                 required: false
                 type: string
@@ -53,8 +49,6 @@ jobs:
             - name: Setup
               if: inputs.has_code_changes == 'true'
               uses: ./.actions/.github/workflows/setup
-              with:
-                  torch-commit: ${{ inputs.torch-commit }}
             - name: Build
               if: inputs.has_code_changes == 'true'
               shell: bash

.github/workflows/_test.yml

@@ -23,10 +23,6 @@ on:
                 description: |
                     Set the maximum (in minutes) how long the workflow should take to finish
                       timeout-minutes:
-            torch-commit:
-                required: true
-                type: string
-                description: torch-commit
             has_code_changes:
                 required: false
                 type: string
@@ -89,7 +85,6 @@ jobs:
               if: inputs.has_code_changes == 'true'
               uses: ./.actions/.github/workflows/setup
               with:
-                  torch-commit: ${{ inputs.torch-commit }}
                   wheels-artifact: torch-xla-wheels
             - name: Fetch CPP test binaries
               if: inputs.has_code_changes == 'true' && matrix.run_cpp_tests
@@ -112,18 +107,6 @@ jobs:
                   pip install fsspec
                   pip install rich
                   pip install flax
-            - name: Checkout PyTorch Repo
-              if: inputs.has_code_changes == 'true'
-              uses: actions/checkout@v4
-              with:
-                  repository: pytorch/pytorch
-                  path: pytorch
-                  ref: ${{ inputs.torch-commit }}
-            - name: Checkout PyTorch/XLA Repo
-              if: inputs.has_code_changes == 'true'
-              uses: actions/checkout@v4
-              with:
-                  path: pytorch/xla
             - name: Extra CI deps
               if: inputs.has_code_changes == 'true'
               shell: bash

.github/workflows/_tpu_ci.yml

@@ -2,10 +2,6 @@ name: TPU Integration Test
 on:
   workflow_call:
     inputs:
-      torch-commit:
-        required: false
-        type: string
-        description: torch-commit
       timeout-minutes:
         required: false
         type: number
@@ -42,7 +38,6 @@ jobs:
         if: inputs.has_code_changes == 'true'
         uses: ./.actions/.github/workflows/setup
         with:
-          torch-commit: ${{ inputs.torch-commit }}
           wheels-artifact: torch-xla-wheels
 
       - name: Install test dependencies

.github/workflows/build_and_test.yml

@@ -26,29 +26,21 @@ jobs:
       base_sha: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
       head_sha: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
 
-  get-torch-commit:
+  report-no-code-changes:
     needs: [check_code_changes]
     runs-on: ubuntu-24.04
-    outputs:
-      torch_commit: ${{ steps.commit.outputs.torch_commit }}
     steps:
-      - name: Get latest torch commit
-        id: commit
-        if: needs.check_code_changes.outputs.has_code_changes == 'true'
-        run: |
-          echo "torch_commit=$(git ls-remote https://github.com/pytorch/pytorch.git HEAD | awk '{print $1}')" >> "$GITHUB_OUTPUT"
       - name: Report no code changes
-        if: needs.check_code_changes.outputs.has_code_changes == 'false'
         run: |
           echo "No code changes were detected that require running the full test suite."
+    if: needs.check_code_changes.outputs.has_code_changes == 'false'
 
   build-torch-xla:
     name: "Build PyTorch/XLA"
     uses: ./.github/workflows/_build_torch_xla.yml
-    needs: [check_code_changes, get-torch-commit]
+    needs: [check_code_changes]
     with:
       dev-image: us-central1-docker.pkg.dev/tpu-pytorch-releases/docker/development:3.12_tpuvm
-      torch-commit: ${{needs.get-torch-commit.outputs.torch_commit}}
       timeout-minutes: 45  # Takes ~20m as of 2025/5/30.
       has_code_changes: ${{ needs.check_code_changes.outputs.has_code_changes }}
       runner: linux.24xlarge
@@ -58,13 +50,12 @@ jobs:
   test-python-cpu:
     name: "CPU tests"
     uses: ./.github/workflows/_test.yml
-    needs: [build-torch-xla, check_code_changes, get-torch-commit]
+    needs: [build-torch-xla, check_code_changes]
     with:
       dev-image: us-central1-docker.pkg.dev/tpu-pytorch-releases/docker/development:3.12_tpuvm
       timeout-minutes: 45  # Takes ~26m as of 2025/5/30.
       collect-coverage: false
       runner: linux.24xlarge
-      torch-commit: ${{needs.get-torch-commit.outputs.torch_commit}}
       has_code_changes: ${{ needs.check_code_changes.outputs.has_code_changes }}
     secrets:
       gcloud-service-key: ${{ secrets.GCLOUD_SERVICE_KEY }}

.github/workflows/setup/action.yml

@@ -1,8 +1,5 @@
 name: Set up PyTorch/XLA
 inputs:
-    torch-commit:
-        type: string
-        description: PyTorch commit to check out, if provided
     wheels-artifact:
         type: string
         description: |
@@ -16,6 +13,7 @@ runs:
           run: |
               ls -la
               rm -rvf ${GITHUB_WORKSPACE}/*
+
         - name: Setup gcloud
           shell: bash
           run: |
@@ -25,24 +23,37 @@ runs:
           # reason composite actions don't support secrets.
           # https://docs.github.com/en/actions/using-workflows/avoiding-duplication
           if: ${{ env.GCLOUD_SERVICE_KEY }}
+
         - name: Checkout PyTorch Repo
           uses: actions/checkout@v4
           with:
               repository: pytorch/pytorch
               path: pytorch
-              ref: ${{ inputs.torch-commit }}
-              submodules: recursive
-          if: ${{ inputs.torch-commit }}
+
         - name: Checkout PyTorch/XLA Repo
           uses: actions/checkout@v4
           with:
               path: pytorch/xla
+
+        # Fetch and checkout to the pinned PyTorch commit.
+        - name: Checkout to PyTorch Commit Pin
+          working-directory: pytorch
+          shell: bash
+          env:
+            TORCH_COMMIT_FILE: ".torch_commit"
+          run: |
+            COMMIT=$(tail -1 "xla/$TORCH_COMMIT_FILE")
+            git fetch --no-recurse-submodules origin $COMMIT
+            git checkout --no-recurse-submodules FETCH_HEAD
+            git submodule update --init --recursive
+
         - name: Fetch PyTorch/XLA packages
           uses: actions/download-artifact@v5
           with:
               name: ${{ inputs.wheels-artifact }}
               path: /tmp/wheels/
           if: ${{ inputs.wheels-artifact }}
+
         - name: Install wheels
           shell: bash
           run: |

.torch_commit

@@ -0,0 +1,2 @@
+# 2025-09-17
+928ac57c2ab03f9f79376f9995553eea2e6f4ca8

CONTRIBUTING.md

@@ -37,7 +37,7 @@ working with:
 
 Next, we need to clone the forked repos locally so that we can make changes.
 
-On your Linuc machine, decide a directory as your workspace. Make sure that
+On your Linux machine, decide a directory as your workspace. Make sure that
 this directory and all of its ancestors are publically readable. Then run
 the following commands on this machine:
 
@@ -58,6 +58,28 @@ git clone --recursive [email protected]:<your-github-user-name>/vision.git
 git clone --recursive [email protected]:<your-github-user-name>/pytorch-xla.git pytorch/xla
 ```
 
+### Pinned PyTorch Version
+
+Since PR #9654, PyTorch/XLA started pinnning a PyTorch version. The pinned
+commit can be found in `.torch_commit` file at the root directory. Note that
+the pinned PyTorch version guarantees all PyTorch/XLA tests are passing
+whenever the underlying PyTorch is compiled at that specific commit. Therefore,
+specially for development, it's recommended that PyTorch is compiled at that
+specific commit. Otherwise you might end up with all kinds of errors: from
+build errors, to segmentation faults. So, make sure to check out that version:
+
+```bash
+# Go to PyTorch directory.
+cd $WORKSPACE_DIR/pytorch
+
+# Retrieve the PyTorch commit pin inside PyTorch/XLA directory.
+# Note: it's located in the last line of `.torch_commit`.
+COMMIT=$(tail -1 "xla/.torch_commit")
+
+# Create a branch (optional) and jump at that commit.
+git checkout -b pin "$COMMIT"
+```
+
 ### Setting up Remote Tracking
 
 From time to time, we'll need to bring our forked repos up to date with the

infra/ansible/roles/build_srcs/tasks/main.yaml

@@ -1,8 +1,8 @@
 - name: Read PyTorch pin
-  ansible.builtin.command: cat {{ (src_root, 'pytorch/xla/.torch_pin') | path_join }}
+  ansible.builtin.shell: |
+    cat {{ (src_root, 'pytorch/xla/.torch_pin') | path_join }} 2> /dev/null ||
+      tail -1 {{ (src_root, 'pytorch/xla/.torch_commit') | path_join }}
   register: torch_pin
-  # Pin may not exist
-  ignore_errors: true
 
 - name: Checkout PyTorch pin
   # ansible.builtin.git wants to fetch the entire history, so check out the pin manually
@@ -21,7 +21,6 @@
     chdir: "{{ (src_root, 'pytorch') | path_join }}"
   args:
     executable: /bin/bash
-  when: torch_pin is succeeded
 
 - name: Build PyTorch
   ansible.builtin.command:

scripts/build_developer.sh

@@ -56,6 +56,11 @@ if [ "$_BUILD_BASE" == "pytorch" ]; then
   # Change to the pytorch directory.
   cd $_SCRIPT_DIR/../..
 
+  TORCH_COMMIT="xla/.torch_commit"
+  if [ -e "$TORCH_COMMIT" ]; then
+    git checkout $(tail -1 "$TORCH_COMMIT")
+  fi
+
   # Remove any leftover old wheels and old installation.
   pip uninstall torch -y
   python3 setup.py clean