SC-74483: Correct the local variables and secrets model - #100
Merged
Conversation
The pages described a variables model the CLI never implemented. Three
of them stated that 'inputType: Secret' with 'secretKey' is normalized
into 'ProjectVariable' with 'variableKey' on save; the CLI writes and
keeps whichever of the two you declare, and because they read their
local values from different files ('.secrets' versus
'.quix.yaml.variables') the claim sent readers to the wrong file. Both
mechanisms are now documented side by side, everywhere they appear.
Project variables and variable groups were undocumented as a local
concern: '.quix.yaml.variables' is described in all three of its roles,
including that 'quix init' seeds the keys and that a group's secret
member resolves there rather than from '.secrets'. The '.env'
walkthroughs gain the Project Variables and Groups sections, secret
values are shown blank with an explanation of how they still reach the
application, and '.gitignore' lists its sixth entry.
'quix cloud variables' had no page at all while the CLI's own help
linked to one, so the reference section now exists. Stale console
output is corrected against real runs: the compose service is
'kafka_broker', deployment names lowercase with underscores in service
and container names, and the broker console is served on port 8080.
Every statement was verified by running the CLI. The generated pages
come from 'quix docs'; the site builds with no new warnings.
'pipeline update' has options that decide which applications it touches and what happens to their variables, and none were described: notably '--reset', which empties the deployments and topics sections before rebuilding them, discarding hand-tuned replica counts, resource limits, versions and topic settings. It now carries a warning saying so. 'pipeline up' gains its '--keep-variables' and '--preserve-dockerignore' behaviour. 'apps variables import' contradicted itself about whether existing values are replaced. They always are: the command passes replaceAppVariables unconditionally, and the only entries it leaves alone are secrets and secret group members, whose defaultValue holds a key rather than a value. The commands summary gains the project variables group and drops a duplicated topics row; the two context-environment pages agree on one spelling of the command. Nav order for the new pages now matches what 'quix docs' emits, so regenerating is a no-op.
The five 'cloud variables' reference pages were transcribed from the CLI's --help text, which renders differently from the command model the generator reads: it omits an Aliases line when the only alias matches the command name, and it showed the environment argument as required where the model has it optional. Regenerating with 'quix docs' corrects both. The two 'up' pages pick up the compose.local.yaml naming fix from the CLI. 'cloud/users/tokens/create.gen.md' is deliberately left alone: its documented default is today plus a year, so regenerating it only replaces one stale date with another.
Every in-repo link on the local development pages pointed at a sibling of the page rather than of the docs root, so all thirteen returned 404 in the built site - the Quickstart link and every CLI reference link the tutorials lean on, plus one carrying a doubled slash. Verified by fetching each from a local build: they now resolve. The remaining 'quix-cloud/...' links are untouched. They are meant to resolve in the assembled documentation site, where quix-cli sits alongside quix-cloud, and cannot resolve in this repository alone.
Two pages one level below the docs root reached sibling sections with a single '../', the prefix a root-level page uses. Every other page at that depth uses '../../', so both were one level short and would land outside the section in the assembled site. The pipeline view image on the template page pointed above the docs root as well, so it never rendered; the file it wants sits in 'docs/images'. Left alone: 'cli-template.md' links to 'cli-reference.md', which does not exist in any form here, and the page is not in the navigation.
'cli-template.md' arrived as a copy of a page from the main documentation site and was dropped from the navigation in 6d1a752 (August 2024) when its sibling was relocated to How-To instead. Nothing has linked to it since, so it has been unreachable for two years, and its walkthrough still uses the command names from before the CLI was restructured. Its cross-section links never resolved here either - 'cli-reference.md' has never existed in this repository in any form. The pipeline screenshot goes with it, as that page was its only user. Every link warning the build now reports is a deliberate reference to a sibling documentation section, resolved when the site is assembled.
The local development story is told through three files, but the pages that walk a reader through running an application stopped at '.env'. Neither mentioned '.secrets' or '.quix.yaml.variables', so the two files a value actually has to be typed into were invisible to anyone following that path, and the blank line a secret leaves behind looked like something to fix. 'quix run' now documents where each variable comes from, including the secrets it resolves from those files as it starts the process and the deployment that decides which key each one is read by - previously the page described the '.env' file alone. The local development walkthrough gains the file model itself: which file holds what, keyed by what, and why the committed YAML carries only a reference.
An adversarial pass over these pages checked 41 claims against the merged CLI and found eight that did not hold. The one that mattered promised that typing a value beside a blank secret line gets it stored: only the Secrets section does that, so a reader following it for a secret project variable or a group member was being sent to a file nothing reads. Those two now point at '.quix.yaml.variables' and say plainly that a value typed into '.env' is used by the run that reads it but never promoted out of it. The rest were smaller and equally checkable: the import page omitted project variables from the entries it never overwrites and never mentioned the '--reset' option its own generated block documents; a secret was described as masked in the UI where the API in fact withholds it, wording that collided with how HiddenText is described a page away; 'cloud variables' stores the secret flag per value but reports it per key, so one secret environment marks the whole row; two quoted console blocks on the update page had drifted from what the command prints; and '--verbose' shows the variables read from '.env' rather than the environment the process ends up with. Also documents the behaviour of the accompanying CLI change: a refresh keeps a line it cannot resolve rather than blanking it, which leaves plaintext behind when a variable becomes secret until the file is rebuilt.
emanuel-quix
marked this pull request as ready for review
August 11, 2026 09:07
luisquix
approved these changes
Aug 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The variables and secrets documentation now matches what the CLI actually does: both secret mechanisms are described side by side with the file each one reads its value from, project variables and variable groups are covered as a local concern for the first time, and the project variables reference section the CLI's own help already links to now exists. Three pages previously stated that a secret declared with
inputType: Secretis normalized into a project variable when saved, which is not what the CLI writes and sent readers to the wrong file to put their values in. Link warnings drop from 31 to 14 on the way, because half of them were local development links that returned 404 rather than the cross-repository references they were assumed to be.