From b32b65a31bf3dd760d377e1d7614f354d0ae8d9a Mon Sep 17 00:00:00 2001 From: Marc Jakobi Date: Thu, 13 Aug 2026 23:05:19 +0200 Subject: [PATCH] docs: `[access-tokens]` config option Signed-off-by: Marc Jakobi --- docs/guides/access-tokens.md | 75 +++++++++++++++++++++++++ docs/guides/index.md | 3 + docs/reference/environment-variables.md | 12 ++++ docs/reference/index.md | 2 +- docs/tutorial/04-adding-dependencies.md | 5 ++ 5 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 docs/guides/access-tokens.md diff --git a/docs/guides/access-tokens.md b/docs/guides/access-tokens.md new file mode 100644 index 0000000..a2f36c6 --- /dev/null +++ b/docs/guides/access-tokens.md @@ -0,0 +1,75 @@ +--- +slug: /guides/access-tokens +id: access-tokens +title: How to configure access tokens +sidebar_label: Access tokens +--- + +Lux fetches rocks, rockspecs, and git dependencies over HTTP(S). +Access tokens authenticate you with the host, which is required for private +repositories. + +Even for public repositories, configuring an access token is worthwhile: +authenticated requests are less likely to be rate limited. + +## Configure tokens + +You can configure access tokens either in the `[access_tokens]` section of your +config file, or via the `LUX_ACCESS_TOKENS` environment variable. + +Open your config file with: + +```sh +lx config edit +``` + +Then add a `[access_tokens]` section, mapping each host to its token: + +```toml +[access_tokens] +"github.com" = "ghp_1234abcd" +"gitlab.com" = "PAT:glpat-1234abcd" +"codeberg.org" = "cb_1234abcd" +"git.sr.ht" = "s3cr3t" +``` + +:::note +On GitHub Actions runners, Lux will automatically pick up the [`GITHUB_TOKEN`](https://docs.github.com/en/actions/tutorials/authenticate-with-github_token) +environment variable. +::: + +## Token types + +Lux recognizes the following token types: + +| Type | Syntax | Hosts | +|---|---|---| +| Plain token | `` | GitHub, Codeberg, and other Gitea-compatible forges, and SourceHut | +| GitLab personal access token | `PAT:` | GitLab | +| GitLab OAuth2 token | `OAuth2:` | GitLab | + +The type determines how the token is sent, e.g. a GitLab personal access token +is sent in the `PRIVATE-TOKEN` header, while a plain token is sent in the +`Authorization` header. + +## Environment variable + +As an alternative to the config file, set the `LUX_ACCESS_TOKENS` environment +variable to a whitespace-separated list of `host=token` pairs: + +```sh +export LUX_ACCESS_TOKENS="github.com=ghp_1234abcd gitlab.com=OAuth2:glpat-1234abcd" +``` + +## Precedence + +Lux resolves the token for a host in this order: + +1. The `LUX_ACCESS_TOKENS` environment variable. +2. The `[access_tokens]` section of the config file. +3. The `GITHUB_TOKEN` environment variable, for `github.com` only. + +## Git dependencies + +The same tokens are used for git-over-HTTPS authentication when fetching +[git dependencies](/reference/lux-toml#git-dependencies). diff --git a/docs/guides/index.md b/docs/guides/index.md index c405058..8c16e1c 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -18,6 +18,9 @@ Want to get better at using Lux? Look no further than this set of guides. - [How to use Lux with a rockspec file](/guides/rockspec) - [How to declare a workspace with multiple projects](/guides/multi-project-workspaces) +## Configuration +- [How to configure access tokens](/guides/access-tokens) + ## Code Hygiene - [How to test a Lua project](/guides/testing) - [How to format and lint a Lua project](/guides/formatting-linting) diff --git a/docs/reference/environment-variables.md b/docs/reference/environment-variables.md index a3fb7e8..c951951 100644 --- a/docs/reference/environment-variables.md +++ b/docs/reference/environment-variables.md @@ -15,3 +15,15 @@ Secret key for generating TOTP codes for two-factor authentication. Lux reads this variable to automatically generate 2FA codes during `lx upload`, eliminating the need for the `--tfa-code` flag. Obtain the secret from the [2FA settings](https://luarocks.org/settings/two-factor-auth) page on LuaRocks. + +## `LUX_ACCESS_TOKENS` + +Access tokens for fetching from private repositories, as a whitespace-separated +list of `host=token` pairs. + +```sh +export LUX_ACCESS_TOKENS="github.com=ghp_1234abcd gitlab.com=OAuth2:glpat-1234abcd" +``` + +See [How to configure access tokens](/guides/access-tokens) for supported token +types and hosts. diff --git a/docs/reference/index.md b/docs/reference/index.md index d34da2b..faeefb8 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -11,5 +11,5 @@ sidebar_position: 3 Detailed reference documentation for Lux configuration and tooling. - [lux.toml reference](/reference/lux-toml). All fields, build backends, and test specifications. -- [Environment variables reference](/reference/environment-variables). `LUX_API_KEY` and `LUAROCKS_2FA_SECRET`. +- [Environment variables reference](/reference/environment-variables). `LUX_API_KEY`, `LUAROCKS_2FA_SECRET`, and `LUX_ACCESS_TOKENS`. - [CLI reference](/reference/cli). All `lx` subcommands and global options, auto-generated from the man page. diff --git a/docs/tutorial/04-adding-dependencies.md b/docs/tutorial/04-adding-dependencies.md index 45986d5..72275a7 100644 --- a/docs/tutorial/04-adding-dependencies.md +++ b/docs/tutorial/04-adding-dependencies.md @@ -25,6 +25,11 @@ Added argparse 0.7.1 This may take a while depending on your internet connection! ::: +:::tip +To avoid hitting rate limits on hosts +like GitHub, see [How to configure access tokens](/guides/access-tokens). +::: + ## Testing Our Changes To check whether `argparse` is loaded, we can enter a Lua REPL and play around