repository scope requires --github-relay-read-only

Error message

repository scope requires --github-relay-read-only

What it means

GitHubRelay::from_flags validates that repository scoping options are only meaningful when the relay is enabled. When --github-relay-read-only is not enabled but --github-relay-all-repos or --github-relay-repo was passed, mise rejects the combination rather than silently ignoring the repo flags.

Source

Thrown at src/github_relay.rs:24

#[derive(Clone, Debug, Default)]
pub(crate) struct Scope {
    #[cfg(unix)]
    options: Options,
    #[cfg(any(unix, test))]
    repositories: std::collections::BTreeSet<String>,
    #[cfg(any(unix, test))]
    all: bool,
}

impl Scope {
    pub(crate) fn from_flags(
        enabled: bool,
        repositories: &[String],
        all: bool,
    ) -> Result<Option<Self>> {
        if !enabled {
            if all || !repositories.is_empty() {
                bail!("repository scope requires --github-relay-read-only");
            }
            return Ok(None);
        }
        if all != repositories.is_empty() {
            bail!("choose --github-relay-repo OWNER/REPO or --github-relay-all-repos, not both");
        }
        let repositories: std::collections::BTreeSet<String> = repositories
            .iter()
            .map(|repo| repository(repo))
            .collect::<Result<_>>()?;
        #[cfg(not(any(unix, test)))]
        let _ = repositories;
        Ok(Some(Self {
            #[cfg(unix)]
            options: Options::default(),
            #[cfg(any(unix, test))]
            repositories,
            #[cfg(any(unix, test))]

View on GitHub (pinned to afd2eddd3a)

Solutions

Add `--github-relay-read-only` to the command line to enable the relay.
If you don't want the relay, remove the --github-relay-repo / --github-relay-all-repos flags.
Set the relay enabled setting in mise.toml instead if you want it always on, then drop the CLI flag conflict.

Example fix

// before
mise --github-relay-repo owner/repo exec -- node build.js
// after
mise --github-relay-read-only --github-relay-repo owner/repo exec -- node build.js

Defensive patterns

Strategy: validation

Validate before calling

# shell: fail fast before invoking mise
if [[ -n "$RELAY_REPOS" || -n "$RELAY_ALL" ]] && ! $RELAY_ENABLED; then
  echo "add --github-relay-read-only or drop repo flags" >&2; exit 1
fi

Type guard

fn relay_flags_consistent(enabled: bool, repos: &[String], all: bool) -> bool {
    !enabled == !(all || !repos.is_empty())
}

Try / catch

match Scope::from_flags(enabled, repos, all) {
    Err(e) if e.to_string().contains("requires --github-relay-read-only") => {
        // retry with the enable flag added
    }
    r => r,
}

Prevention

Always pair repo/all scope flags with --github-relay-read-only.
Keep relay flags in one wrapper script so the enable flag is never dropped.
Prefer configuring [github_relay] in mise.toml over ad-hoc CLI flags.

When it happens

Trigger: Calling from_flags with enabled=false while `all` is true or `repositories` is non-empty — i.e. CLI invocation like `mise --github-relay-repo owner/repo <cmd>` without `--github-relay-read-only`.

Common situations: Copy-pasting an older command line that used repo flags before the enable flag was introduced; assuming repo flags imply the relay is on; scripted aliases that dropped the enable flag.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/c532cb87f6f28a71. Report an issue: GitHub.