urfave/cli · error

empty github token

Error message

empty github token

What it means

SetMkdocsRemoteActionFunc validates the --github-token command option before performing GitHub remote configuration for docs builds. If the option is missing or contains only whitespace (it is TrimSpace'd first), the action aborts with this error because a GitHub API token is required to set up the remote.

Source

Thrown at scripts/build.go:614

	}

	if err := runCmd(ctx, "mkdocs", "--version"); err == nil {
		return nil
	}

	if cmd.Bool("upgrade-pip") {
		if err := runCmd(ctx, "pip", "install", "-U", "pip"); err != nil {
			return err
		}
	}

	return runCmd(ctx, "pip", "install", "-r", "mkdocs-requirements.txt")
}

func SetMkdocsRemoteActionFunc(ctx context.Context, cmd *cli.Command) error {
	ghToken := strings.TrimSpace(cmd.String("github-token"))
	if ghToken == "" {
		return errors.New("empty github token")
	}

	if err := os.Chdir(cmd.String("top-dir")); err != nil {
		return err
	}

	if err := runCmd(ctx, "git", "remote", "rm", "origin"); err != nil {
		return err
	}

	return runCmd(
		ctx,
		"git", "remote", "add", "origin",
		fmt.Sprintf("https://x-access-token:%[1]s@github.com/urfave/cli.git", ghToken),
	)
}

func LintActionFunc(ctx context.Context, cmd *cli.Command) error {

View on GitHub (pinned to 1a4deb4f5a)

Solutions

1. Pass the token: --github-token "$GH_TOKEN" with the environment variable exported, or provide the value directly in CI secret configuration.
2. Verify the CI workflow actually maps the secret (e.g. env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}) to the step.
3. Check for typos in the variable name that would expand to an empty string.

Example fix

// before
run: ./build mkdocs-remote --github-token ""
// after
run: ./build mkdocs-remote --github-token "${{ secrets.GITHUB_TOKEN }}"

token := os.Getenv("GH_TOKEN")
if strings.TrimSpace(token) == "" {
	return errors.New("GH_TOKEN must be set before running mkdocs remote setup")
}

if err := action(ctx, cmd); err != nil {
	if strings.Contains(err.Error(), "empty github token") {
		return fmt.Errorf("provide --github-token or set GH_TOKEN: %w", err)
	}
	return err
}

When it happens

Trigger: Running the build tooling's mkdocs remote action without passing --github-token, or passing it an empty/whitespace-only value (e.g. GH_TOKEN env var is unset and expanded to empty in a shell script).

Common situations: CI pipelines where the secret (e.g. secrets.GITHUB_TOKEN) is not wired into the workflow step, local runs without exporting the token, or quoting mistakes yielding an empty string.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• got nil/empty layouts slice
• goimports needed
• args %s has max 0, not parsing argument
• args %s has min[%d] > max[%d], not parsing argument
• StopOnNthArg must be non-negative, got %d

AI-assisted analysis of urfave/cli@1a4deb4f5a (2026-08-31). Data as JSON: /api/errors/5f7e061786cb68af. Report an issue: GitHub.