docs: show information about github rate limits when erroring due to …

…403 (#2856)

Fixes #2428

docs/troubleshooting.md

@@ -122,3 +122,22 @@ We also urge users to look after the plugins they use, and urge plugin authors t
 the users they serve.
 
 For more details see [SECURITY.md](https://github.com/jdx/mise/blob/main/SECURITY.md).
+
+## 403 Forbidden when installing a tool
+
+You may get an error like one of the following:
+
+```text
+HTTP status client error (403 Forbidden) for url
+403 API rate limit exceeded for
+```
+
+This can happen if the tool is hosted on GitHub, and you've hit the API rate limit. This is especially
+common running mise in a CI environment like GitHub Actions. If you don't have a `GITHUB_TOKEN`
+set, the rate limit is quite low. You can fix this by creating a GitHub token (which needs no scopes)
+by going to <https://github.com/settings/tokens> and setting it as an environment variable. You can
+use any of the following (in order of preference):
+
+- `MISE_GITHUB_TOKEN`
+- `GITHUB_TOKEN`
+- `GITHUB_API_TOKEN`

src/main.rs

@@ -2,6 +2,7 @@ use crate::cli::version::VERSION;
 use crate::cli::Cli;
 use color_eyre::{Section, SectionExt};
 use eyre::Report;
+use indoc::indoc;
 use itertools::Itertools;
 
 #[cfg(test)]
@@ -84,14 +85,30 @@ fn handle_err(err: Report) -> eyre::Result<()> {
             return Ok(());
         }
     }
+    show_github_rate_limit_err(&err);
     if cfg!(not(debug_assertions)) && log::max_level() < log::LevelFilter::Debug {
-        display_friendly_err(err);
+        display_friendly_err(&err);
         exit(1);
     }
     Err(err)
 }
 
-fn display_friendly_err(err: Report) {
+fn show_github_rate_limit_err(err: &Report) {
+    let msg = format!("{err:?}");
+    if msg.contains("HTTP status client error (403 Forbidden) for url (https://api.github.com") {
+        warn!("GitHub API returned a 403 Forbidden error. This likely means you have exceeded the rate limit.");
+        if env::GITHUB_TOKEN.is_none() {
+            warn!(indoc!(
+                r#"GITHUB_TOKEN is not set. This means mise is making unauthenticated requests to GitHub which have a lower rate limit.
+                   To increase the rate limit, set the GITHUB_TOKEN environment variable to a GitHub personal access token.
+                   Create a token at https://github.com/settings/tokens and set it as GITHUB_TOKEN in your environment.
+                   You do not need to give this token any scopes."#
+            ));
+        }
+    }
+}
+
+fn display_friendly_err(err: &Report) {
     for err in err.chain() {
         error!("{err}");
     }

src/plugins/asdf_plugin.rs

@@ -8,7 +8,7 @@ use crate::timeout::run_with_timeout;
 use crate::ui::multi_progress_report::MultiProgressReport;
 use crate::ui::progress_report::SingleReport;
 use crate::ui::prompt;
-use crate::{dirs, exit, lock_file, plugins, registry};
+use crate::{dirs, env, exit, lock_file, plugins, registry};
 use clap::Command;
 use console::style;
 use contracts::requires;
@@ -425,12 +425,17 @@ Plugins could support local directories in the future but for now a symlink is r
 
 fn build_script_man(name: &str, plugin_path: &Path) -> ScriptManager {
     let plugin_path_s = plugin_path.to_string_lossy().to_string();
-    ScriptManager::new(plugin_path.to_path_buf())
+    let mut sm = ScriptManager::new(plugin_path.to_path_buf())
         .with_env("ASDF_PLUGIN_PATH", plugin_path_s.clone())
         .with_env("RTX_PLUGIN_PATH", plugin_path_s.clone())
         .with_env("RTX_PLUGIN_NAME", name.to_string())
         .with_env("RTX_SHIMS_DIR", *dirs::SHIMS)
         .with_env("MISE_PLUGIN_NAME", name.to_string())
         .with_env("MISE_PLUGIN_PATH", plugin_path)
-        .with_env("MISE_SHIMS_DIR", *dirs::SHIMS)
+        .with_env("MISE_SHIMS_DIR", *dirs::SHIMS);
+    if let Some(token) = &*env::GITHUB_TOKEN {
+        // asdf plugins often use GITHUB_API_TOKEN as the env var for GitHub API token
+        sm = sm.with_env("GITHUB_API_TOKEN", token.to_string());
+    }
+    sm
 }