Skip GitHub fast path when rate-limited

crates/uv-git/src/git.rs

@@ -19,6 +19,8 @@ use uv_git_types::{GitHubRepository, GitOid, GitReference};
 use uv_static::EnvVars;
 use uv_version::version;
 
+use crate::rate_limit::GITHUB_RATE_LIMIT_STATUS;
+
 /// A file indicates that if present, `git reset` has been done and a repo
 /// checkout is ready to go. See [`GitCheckout::reset`] for why we need this.
 const CHECKOUT_READY_LOCK: &str = ".ok";
@@ -786,7 +788,15 @@ fn github_fast_path(
         }
     };
 
-    let url = format!("https://api.github.com/repos/{owner}/{repo}/commits/{github_branch_name}");
+    // Check if we're rate-limited by GitHub before determining the FastPathRev
+    if GITHUB_RATE_LIMIT_STATUS.is_active() {
+        debug!("Skipping GitHub fast path attempt for: {url} (rate-limited)");
+        return Ok(FastPathRev::Indeterminate);
+    }
+
+    let base_url = std::env::var(EnvVars::UV_GITHUB_FAST_PATH_URL)
+        .unwrap_or("https://api.github.com/repos".to_owned());
+    let url = format!("{base_url}/{owner}/{repo}/commits/{github_branch_name}");
 
     let runtime = tokio::runtime::Builder::new_current_thread()
         .enable_all()
@@ -806,6 +816,11 @@ fn github_fast_path(
 
         let response = request.send().await?;
 
+        // Mark that we are currently being rate-limited by GitHub.
+        if response.status() == StatusCode::TOO_MANY_REQUESTS {
+            GITHUB_RATE_LIMIT_STATUS.activate();
+        }
+
         // GitHub returns a 404 if the repository does not exist, and a 422 if it exists but GitHub
         // is unable to resolve the requested revision.
         response.error_for_status_ref()?;

crates/uv-git/src/lib.rs

@@ -7,5 +7,6 @@ pub use crate::source::{Fetch, GitSource, Reporter};
 
 mod credentials;
 mod git;
+mod rate_limit;
 mod resolver;
 mod source;

crates/uv-git/src/rate_limit.rs

@@ -0,0 +1,26 @@
+use std::sync::LazyLock;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+/// A global state on whether we are being rate-limited by GitHub's REST API.
+/// If we are, avoid "fast-path" attempts.
+pub(crate) static GITHUB_RATE_LIMIT_STATUS: LazyLock<GitHubRateLimitStatus> =
+    LazyLock::new(GitHubRateLimitStatus::default);
+
+/// GitHub REST API rate limit status tracker.
+///
+/// ## Assumptions
+///
+/// The rate limit timeout duration is much longer than the runtime of a `uv` command.
+/// And so we do not need to invalidate this state based on `x-ratelimit-reset`.
+#[derive(Debug, Default)]
+pub(crate) struct GitHubRateLimitStatus(AtomicBool);
+
+impl GitHubRateLimitStatus {
+    pub(crate) fn activate(&self) {
+        self.0.store(true, Ordering::SeqCst);
+    }
+
+    pub(crate) fn is_active(&self) -> bool {
+        self.0.load(Ordering::SeqCst)
+    }
+}

crates/uv-git/src/resolver.rs

@@ -6,15 +6,17 @@ use std::sync::Arc;
 use dashmap::DashMap;
 use dashmap::mapref::one::Ref;
 use fs_err::tokio as fs;
+use reqwest::StatusCode;
 use reqwest_middleware::ClientWithMiddleware;
 use tracing::debug;
 
 use uv_cache_key::{RepositoryUrl, cache_digest};
 use uv_fs::LockedFile;
 use uv_git_types::{GitHubRepository, GitOid, GitReference, GitUrl};
+use uv_static::EnvVars;
 use uv_version::version;
 
-use crate::{Fetch, GitSource, Reporter};
+use crate::{Fetch, GitSource, Reporter, rate_limit::GITHUB_RATE_LIMIT_STATUS};
 
 #[derive(Debug, thiserror::Error)]
 pub enum GitResolverError {
@@ -72,10 +74,18 @@ impl GitResolver {
             return Ok(None);
         };
 
+        // Check if we're rate-limited by GitHub, before determining the Git reference
+        if GITHUB_RATE_LIMIT_STATUS.is_active() {
+            debug!("Rate-limited by GitHub. Skipping GitHub fast path attempt for: {url}");
+            return Ok(None);
+        }
+
         // Determine the Git reference.
         let rev = url.reference().as_rev();
 
-        let url = format!("https://api.github.com/repos/{owner}/{repo}/commits/{rev}");
+        let base_url = std::env::var(EnvVars::UV_GITHUB_FAST_PATH_URL)
+            .unwrap_or("https://api.github.com/repos".to_owned());
+        let url = format!("{base_url}/{owner}/{repo}/commits/{rev}");
 
         debug!("Querying GitHub for commit at: {url}");
         let mut request = client.get(&url);
@@ -86,13 +96,17 @@ impl GitResolver {
         );
 
         let response = request.send().await?;
-        if !response.status().is_success() {
+        let status = response.status();
+        if !status.is_success() {
             // Returns a 404 if the repository does not exist, and a 422 if GitHub is unable to
             // resolve the requested rev.
-            debug!(
-                "GitHub API request failed for: {url} ({})",
-                response.status()
-            );
+            debug!("GitHub API request failed for: {url} ({})", status);
+
+            // Mark that we are currently being rate-limited by GitHub.
+            if status == StatusCode::TOO_MANY_REQUESTS {
+                GITHUB_RATE_LIMIT_STATUS.activate();
+            }
+
             return Ok(None);
         }
 

crates/uv-static/src/env_vars.rs

@@ -667,6 +667,10 @@ impl EnvVars {
     #[attr_hidden]
     pub const UV_TEST_INDEX_URL: &'static str = "UV_TEST_INDEX_URL";
 
+    /// Used to set the GitHub fast-path url for tests.
+    #[attr_hidden]
+    pub const UV_GITHUB_FAST_PATH_URL: &'static str = "UV_GITHUB_FAST_PATH_URL";
+
     /// Hide progress messages with non-deterministic order in tests.
     #[attr_hidden]
     pub const UV_TEST_NO_CLI_PROGRESS: &'static str = "UV_TEST_NO_CLI_PROGRESS";

crates/uv/tests/it/edit.rs

@@ -496,6 +496,48 @@ fn add_git_private_raw() -> Result<()> {
     Ok(())
 }
 
+#[tokio::test]
+#[cfg(feature = "git")]
+async fn add_git_private_rate_limited_by_github_rest_api() -> Result<()> {
+    use uv_client::DEFAULT_RETRIES;
+
+    let context = TestContext::new("3.12");
+    let token = decode_token(READ_ONLY_GITHUB_TOKEN);
+
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .respond_with(ResponseTemplate::new(429))
+        .expect(1 + u64::from(DEFAULT_RETRIES))
+        .mount(&server)
+        .await;
+
+    let pyproject_toml = context.temp_dir.child("pyproject.toml");
+    pyproject_toml.write_str(indoc! {r#"
+        [project]
+        name = "project"
+        version = "0.1.0"
+        requires-python = ">=3.12"
+        dependencies = []
+    "#})?;
+
+    uv_snapshot!(context.filters(), context
+        .add()
+        .arg(format!("uv-private-pypackage @ git+https://{token}@github.com/astral-test/uv-private-pypackage"))
+        .env("UV_GITHUB_FAST_PATH_URL", server.uri()), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 2 packages in [TIME]
+    Prepared 1 package in [TIME]
+    Installed 1 package in [TIME]
+     + uv-private-pypackage==0.1.0 (from git+https://github.com/astral-test/uv-private-pypackage@d780faf0ac91257d4d5a4f0c5a0e4509608c0071)
+    ");
+
+    Ok(())
+}
+
 #[test]
 #[cfg(feature = "git")]
 fn add_git_error() -> Result<()> {

crates/uv/tests/it/pip_install.rs

@@ -2071,6 +2071,36 @@ fn install_git_public_https_missing_branch_or_tag() {
     "###);
 }
 
+#[tokio::test]
+#[cfg(feature = "git")]
+async fn install_git_public_rate_limited_by_github_rest_api() {
+    use uv_client::DEFAULT_RETRIES;
+
+    let context = TestContext::new("3.12");
+
+    let server = MockServer::start().await;
+    Mock::given(method("GET"))
+        .respond_with(ResponseTemplate::new(429))
+        .expect(1 + u64::from(DEFAULT_RETRIES))
+        .mount(&server)
+        .await;
+
+    uv_snapshot!(context.filters(), context
+        .pip_install()
+        .arg("pip-test-package @ git+https://github.com/pypa/pip-test-package@5547fa909e83df8bd743d3978d6667497983a4b7")
+        .env("UV_GITHUB_FAST_PATH_URL", server.uri()), @r"
+    success: true
+    exit_code: 0
+    ----- stdout -----
+
+    ----- stderr -----
+    Resolved 1 package in [TIME]
+    Prepared 1 package in [TIME]
+    Installed 1 package in [TIME]
+     + pip-test-package==0.1.1 (from git+https://github.com/pypa/pip-test-package@5547fa909e83df8bd743d3978d6667497983a4b7)
+    ");
+}
+
 /// Install a package from a public GitHub repository at a ref that does not exist
 #[test]
 #[cfg(feature = "git")]