nucleate configuration
nucleate needs to know one thing, where the nucleus is, and it can usually work that out. Two more settings name the session branches and let it ask GitHub about private repositories.
nucleateOn this page
Where the nucleus is #
Every command needs the nucleus root. nucleate takes it from the first of these that is set:
- The
--root <path>option. - The
NUCLEATE_ROOTenvironment variable. rootin the config file.- The nearest folder at or above the current one that contains a
.reposfolder.
The last step is why commands run inside a session, or anywhere inside the nucleus, need no configuration at all. The config file matters for commands run from elsewhere: a timer, a script, or nucleate status --session fix-login from your home folder.
If nothing is found:
nucleate: no workspace root: pass --root, set NUCLEATE_ROOT, set `root` in the config file, or run inside a folder that contains .repos
If the root that was found is not a folder:
nucleate: workspace root is not a directory: /home/agent/work
The config file #
The file is ~/.config/nucleate/config.toml. nucleate init writes it; you can also write it by hand. Every key is optional, and a missing file is not an error.
# The nucleus: the folder holding .repos, .worktrees and .seeds.
root = "/home/agent/workspace"
# A file holding a GitHub token, for the merged-pull-request check on
# private repositories.
github_token_file = "/run/agent-tokens/github"
# Session branches are named <branch_prefix>/<session>.
branch_prefix = "workspace"
| Key | Default | Meaning |
|---|---|---|
root |
None | The nucleus root. Used when neither --root nor NUCLEATE_ROOT is set. |
github_token_file |
None | A file whose contents are a GitHub token. Read each time the token is needed, so a file that is rewritten with a fresh token keeps working. |
branch_prefix |
workspace |
The first part of every session branch. The session fix-login works on workspace/fix-login. |
Changing branch_prefix affects sessions created afterwards. A session that already exists keeps the branch recorded in its manifest.
A file that is not valid TOML stops every command, with the file and the position of the mistake:
nucleate: parsing /home/agent/.config/nucleate/config.toml: TOML parse error at line 1, column 8
Where the file is looked for #
| Order | Location |
|---|---|
| 1 | The file named by NUCLEATE_CONFIG. |
| 2 | $XDG_CONFIG_HOME/nucleate/config.toml, when XDG_CONFIG_HOME is set. |
| 3 | ~/.config/nucleate/config.toml. |
Environment variables #
| Variable | Meaning |
|---|---|
NUCLEATE_ROOT |
The nucleus root. Beats the config file; loses to --root. |
NUCLEATE_CONFIG |
The config file to read, in place of the default location. |
NUCLEATE_GITHUB_TOKEN_FILE |
The token file. Beats github_token_file in the config file. |
GH_TOKEN, GITHUB_TOKEN |
A GitHub token itself. See below. |
The GitHub token #
nucleate asks GitHub one question: is this commit the head of a merged pull request? It is part of the safety rule, and it is what lets a squash-merged session clean up after itself.
For a public repository the question needs no token. For a private one it does. The token is taken from the first of these that has a value:
- The
GH_TOKENenvironment variable. - The
GITHUB_TOKENenvironment variable. - The file named by
NUCLEATE_GITHUB_TOKEN_FILE, or bygithub_token_filein the config file.
The token only needs to read pull requests on the repositories in the nucleus. nucleate does not use it for anything else: cloning, fetching and pushing are done by git with git's own credentials.
If there is no token, or the token is wrong or expired, nothing breaks. GitHub's refusal counts as "not merged", and the worktree in question is kept.
On a box built with the recipe #
The box recipe writes this file for the agent user:
root = "/home/agent/workspace"
github_token_file = "/run/agent-tokens/github"
branch_prefix = "workspace"
/run/agent-tokens/github holds a short-lived token that the box replaces every 20 minutes. Because nucleate reads the file each time, it always has a current one. Agent sessions on the box also have GH_TOKEN set from the same file, which takes precedence and comes to the same thing.
Check what nucleate sees:
nucleate available
If that lists your repos from any folder, the root is configured. If it works only inside ~/workspace, the config file is missing or has no root.