Glossary

Sluiceway keeps one GitHub issue, the dashboard, that shows which infrastructure stacks have changes waiting, and deploys a stack when someone ticks its box. This glossary fixes the words used for that.

Language

Stacks

Stack: The smallest thing Sluiceway can preview and deploy on its own. It has its own state, one row on the dashboard and one checkbox. This is Sluiceway’s word, not a tool’s: a Pulumi stack is a stack, and so is an OpenTofu root module with a chosen workspace and var files. Not every stack is a Pulumi stack. Avoid: Unit, project, workspace, module, target

Stack id: The one string that names a stack everywhere: on its row, on its deployment records and in config. It is derived from where the stack lives and what it is called, never chosen, so a stack that is moved or renamed is a new stack. Avoid: Stack name, slug, key

Discovery: Finding the stacks of a repo from its files alone. It never asks a backend and never starts the tool, so it can run in a job that holds no credentials. A stack that no file names does not exist for Sluiceway. Avoid: Detection, lookup, stack listing

Declared stack: A stack that a stacks entry names with tool, because files alone cannot say what it is: an OpenTofu root module, with the workspace and var files the entry gives. Discovery still checks from the files that it can exist, and never starts the tool. Avoid: Configured stack, manual stack, custom stack

Ignored stack: A discovered stack whose stack id matches an ignore glob. It has no row, is never previewed and claims nothing, and config cannot give it settings. When the ignore entry gives a reason, the stack is listed with it in a fold under In sync, and that is all the dashboard says about it. Avoid: Excluded stack, hidden stack, skipped stack

Scans

Scan: One pass that previews stacks and brings the dashboard up to date with the results. Every scan ends with exactly one row for every stack. Avoid: Run, refresh, sync, plan

Full scan: A scan that previews every stack. Avoid: Complete scan, deep scan, rescan (that is the checkbox that asks for one)

Narrowed scan: A scan that previews only the stacks that claim a file changed since the last scan, and keeps every other stack’s row as it is. It is a full scan whenever a changed file has no claimant. Avoid: Partial scan, incremental scan, affected scan, changed stacks

Pool: The fixed number of previews a scan runs at the same time, in one job. It starts the next preview when one finishes, in stack id order, and never previews one stack twice at once. Its size is the concurrency input. Avoid: Workers, threads, matrix, batch

Claim: A stack claims a changed file when the file lies inside the stack’s directory or matches one of the inputs configured for that stack. Several stacks can claim one file. Avoid: Affects, owns, touches, depends on

Scan plan: What a scan decides before it previews anything: a full scan with the reason for it, or a narrowed scan with the stacks to preview and why each one. A narrowed scan that cannot trust its comparison falls back to a full scan. Avoid: Strategy, scan mode, selection

Preparation: A step a tool needs before it can preview a stack, such as OpenTofu’s init of a directory. A scan runs every preparation one at a time and before the pool, and a failed one is a preview failure of each stack that needs it. Avoid: Setup, init step, pre-hook

Check: A pass over the repo’s files and nothing else that says whether Sluiceway understands the setup: the config, the stacks discovery finds, what ignore leaves out and which files no stack claims. It holds no credentials and never starts the tool, so it can never say that a preview will work. Avoid: Validate, lint, dry run, preflight

Diffs

Diff: What deploying one stack would change, told as addresses, ops, tracking changes and the property paths that change. Never values. Avoid: Plan, preview output, changeset

Value: What a property is set to, before or after a deploy. A value never leaves the tool’s adapter: Sluiceway shows that a property changes and never what it changes to, whether or not the tool marks it secret. There are two exceptions, both a repo’s own choice: the tool diff, which it may turn on for the job log, and the value list. Avoid: Secret (a secret is only one kind of value, and all values are treated alike), content, setting

Value list: The property paths a repo names in dashboard.showValues, whose old and new value appear as old → new after the path, everywhere the path does. Only exact paths and globs a person wrote match, never a guess. A value the tool marks secret never shows, and dashboard.redact turns the list off. The diff hash covers a listed value as the row shows it, so a tick approves it. Avoid: Allowlist, safe values, visible values

Property path: Where inside a resource a change happens, as the tool writes it: property names, list indexes and map keys, such as spec.containers[0].image or data["app.properties"]. Never a value. A row shortens a long one, and the summary shows it whole. Avoid: Key path, nested key, JSON path

Tool diff: What a deploy of a stack would change as the tool itself displays it, values included, except the ones the tool marks secret. A second run of the tool, only for a pending stack and only when a repo turns on scan.logDiff. It goes to that stack’s group of the job log and nowhere else, and nothing is decided from it: the row and the diff hash come from the preview. Avoid: Full diff, native diff, raw diff, plan output

Saved plan: The plan file that the fresh preview of apply keeps, for a tool that can save one. When its diff hash is the one the tick approved, the deploy applies that file and nothing else. It lives inside one apply job and is removed on every way out. Avoid: Plan handle, plan artifact, cached plan

Pending: Deploying the stack now would change something, because the code moved. Avoid: Out of sync, dirty, changed

Drift: A change made to real infrastructure outside the code: a property that changed, or an object that is gone. It is shown on the stack’s own row, never on a second row. A stack with drift and nothing to deploy from its code is drifted. A tick deploys the code as it is, which puts the drift back. Avoid: Out-of-band change, skew

Drift check: A run of the tool that compares a stack’s state with real infrastructure and changes neither. With drift.enabled, a scan that a schedule or a person starts runs one for every stack it previews, right after its preview. Its findings join the stack’s diff hash, and apply runs it again before a deploy of a row whose hash covers drift. Avoid: Refresh (that is the tool’s word, and a plain refresh changes the state), drift scan, drift detection run

In sync: Nothing to deploy and no known drift. Avoid: Clean, up to date, green

Diff hash: A fingerprint of everything a stack’s row shows about what a deploy would change. A tick approves that fingerprint, and a deploy goes ahead only if a fresh preview still gives the same one. Avoid: Checksum, signature, plan id

Address: The string that identifies one resource within one stack’s diff. The tool’s adapter defines it and nothing else looks inside it. It is unique within a diff and the same across two identical previews. Avoid: URN, resource id, id

Op: What a deploy would do to one real object: create, update, replace, delete, or nothing. Warnings about destroyed things depend on the op alone. Avoid: Action, step, operation

Tracking change: What a deploy would do to the tool’s record of an object while the object itself is left alone: start tracking it (import), stop tracking it (forget), or track it under a new address (move). It can come with an op or on its own. Avoid: State change, state-only op, no-op

Ticks

Tick: A person checking the box on a stack’s row: a request to deploy that stack exactly as the row shows it. A tick is a commit, not a toggle. Avoid: Approval, selection, click

Ticker: The person whose edit made a tick, as the issue’s edit history names them. The only identity a deploy is authorized against and attributed to. Always a person, never a bot. A tick whose ticker cannot be named deploys nothing. Avoid: Approver, actor, sender, deployer

Edit history: GitHub’s own list of every edit of the dashboard issue, newest first: who made the edit, when, and the whole body right after it. The only source for who ticked. GitHub keeps the original body and the newest 99 edits, and a person can delete the content of an entry. Avoid: Revisions, audit log, event log

Stretch: The unbroken run of edit history entries, from the newest one back, in which a row is ticked with the same stack id and diff hash. The ticker is the editor of its oldest entry. A stretch that holds an entry without a body, or that reaches the end of the kept history, names nobody. Avoid: Streak, window, range

Tick rule: What a person needs in order to tick a stack: a level of access to the repo, or a place on a list of named people who also have write access. It can narrow who may tick, never widen it. Avoid: Approvers, reviewers, allowlist, access list

Refused tick: A tick by a person the stack’s tick rule does not allow. Nothing deploys, the box is cleared and the person is told why. Avoid: Unauthorized tick, rejected tick, denied tick

Unverified tick: A tick whose ticker could not be checked because GitHub gave no answer about their access. Sluiceway fails closed: nothing deploys, the box is cleared, the person is asked for a fresh tick and the job goes red. Avoid: Failed tick, errored tick, unknown tick

Orphan tick: A tick that nothing picked up, so the box is checked but no deploy exists for it and none is on its way. A scan clears it and never deploys it. Avoid: Stale tick, missed tick, lost tick

Dropped tick: A tick on a stack that already has an open deployment. Nothing new starts for it, nobody is checked or told, and the row is brought back to deploying. Avoid: Duplicate tick, ignored tick, second deploy

Rescan box: The one checkbox on the dashboard that belongs to no stack. Ticked by a person with write access, it starts a full scan and deploys nothing. A read-only dashboard has none. Avoid: Refresh button, rescan tick, scan trigger

Reviewer: A person who approves a waiting deploy in GitHub’s own interface, where the repo’s plan offers that. A second gate after the tick, owned by GitHub. Sluiceway only waits for it. Avoid: Approver, second ticker

Update waiting to merge: An open pull request by an author mergeAndDeploy.authors lists, green, and claimed by exactly one stack, that the dashboard offers to merge. Its row shows the stack, the title and the pull request, and a tick on it merges the pull request and deploys the stack as the scan after the merge previews it. It is not a row of a stack and has no diff. Avoid: Renovate row, merge request, pending update, bump row

Merge record: The deployment record resolve opens for a merge it made: on the merge commit, with the ticker and the pull request and no diff hash. It waits for a scan that holds the merge, which ends it and opens the record that deploys the fresh diff. Avoid: Pending merge, merge deployment, pre-deploy

Deploys

Deploy facts: What is known about a stack’s deploys that a preview cannot recompute: that one is running, how the last one ended, who ticked it, and when. Avoid: State, history, status

Deployment record: One attempt to deploy one stack, from tick to result. The only place deploy facts are kept. Avoid: Deploy log, run, job

Open deployment: A deployment record with no result yet. A stack with one is deploying. Avoid: Pending deployment, active deployment, lock

Rehearsal: An apply run with dry-run: true: it takes the deployment record, previews the stack again and checks the diff hash like a deploy, and then deploys nothing. Its record ends as inactive, “rehearsed, nothing was deployed”, the row is pending again, and the recently deployed list says rehearsed. It is not a deploy fact of the stack. Avoid: Dry run (that is the input’s name, not the thing), test deploy, simulation

Settle: To give an open deployment a result when its workflow run ended without reporting one. Avoid: Clean up, time out, expire

Dependency: A stack that another stack names in dependsOn, because it reads something the dependency makes. A tick waits on a dependency only while its row is pending and nobody ticked it: the box is cleared with a note that names the dependency. A stack waits only on the stacks it names, not on theirs. Avoid: Upstream (that is a side of Penny in the header), parent, prerequisite, blocker

Queued stack: A ticked stack whose deployment record waits behind its dependencies, because they were ticked in the same run or are deploying. Its row says “queued behind” them, has no box and counts as deploying. It deploys in a later run once they went out, and never deploys when one of them did not. Avoid: Blocked stack, waiting stack, pending stack (pending is a row state)

Layer: The stacks of a dependency chain that deploy in one workflow run, because nothing they wait behind is still to go out. settle starts the workflow again after a layer, and that run’s resolve starts the next one. Avoid: Wave, stage, batch, level

Outside deploy: A deploy of a stack that did not go through a tick: from a laptop, a script or another pipeline. It is allowed, leaves no deployment record, and the next full scan brings the row back in line. A tick on the stale row finds nothing to deploy, and its record ends as a success that says so. Avoid: Manual deploy, rogue deploy, out-of-band deploy

Credentials

Tool environment: Everything the infrastructure tool needs in order to run: credentials, the state backend, settings. The user’s workflow prepares it before Sluiceway starts, and Sluiceway hands it to the tool whole without looking inside. Avoid: Secrets, env config, credentials config

Dashboard

Bot: The one GitHub identity Sluiceway acts as. It creates and edits the dashboard, writes comments and records deploys. It is never a ticker. Avoid: App, service account, Sluiceway user

Write loop: The one way any mode writes the dashboard body: read the live body, build the new one, skip the write when nothing would change, write, and read back to check. A write that did not stick is tried again from the read, at most three times. Avoid: Retry loop, save, sync, lock

Marker: An HTML comment in the dashboard body that carries machine-readable facts as key="value" pairs. It is the only part of the body a writer ever reads. The visible text next to it is never parsed. Avoid: Tag, annotation, metadata comment

Row block: A stack’s complete entry on the dashboard, bounded so it can be moved or replaced as a unit without reading what is inside. Avoid: Entry, item, section

Carried row: A row block that a writer takes from the live body and writes back as it is, because it has no diff for that stack. It is never read inside and never shortened. Avoid: Kept row, old row, stale row

Counts line: The first line of text on the dashboard: how many stacks are pending, deploying, preview failed and in sync, always all four. It adds how many stacks drifted, how many pending stacks destroy resources and how many rows carry a failure line, each only when it is not 0. Under a header it is centered and every count has a count dot. Avoid: Header line, stats, totals

Scan line: The line under the counts line that says which commit the last scan checked out, when, in which run, and when the last full scan was. Under a header it is centered with the counts line. Avoid: Status line, timestamp, last updated

Row state: Which group a stack’s row belongs to: pending, drift, deploying, in sync, preview failed or queued. A queued row is placed and counted with the deploying ones. It is a label for placing and counting rows. Nothing about a deploy is ever decided from it, with one exception that only holds a deploy back and never starts one: resolve refuses a tick while a dependency’s row is pending. A scan may read it for one thing only: to pick stacks worth previewing again. Avoid: Status, stack state, phase

Preview failure: A stack whose preview did not produce a diff. Its row has no checkbox and links to the run that failed. One stack’s preview failure never stops the others. Avoid: Error row, broken stack, failed stack

Failure line: The note on a stack’s row saying its last deploy failed. It rides on the row wherever the row sits and is not a row state. Avoid: Failed row, failed state, error row

Pending-again line: The note on a pending row whose newest deployment record is a deploy that went out with the same diff hash the row has now: the deploy did not bring the stack in sync. It suggests that a value in the program differs on every run, and points at the tool diff when the job log holds one. It explains a row and decides nothing. Avoid: Flapping, drift, stuck row

Failure reason: Why a preview or a deploy failed, in words from a short fixed list that Sluiceway owns. It never quotes the tool. The tool’s own words stay in the job log, one link away. Avoid: Error message, error text, tool error

Summary: The page of a scan’s workflow run where every stack’s diff is shown, with far more room than the dashboard has. It shows the same kind of facts as a row and nothing more. It opens with an index of the stacks that rows link to, and every stack has its own anchor in it. Shortened and redacted rows link to it, and so does a pending row’s preview link when the stack has no preview page. On the rare scan that does not fit even there, it says so and points at the job log, which holds every diff in full. An apply writes one too, about its one stack: what went out, or why nothing did. Avoid: Full diff, report, native output

Preview page: The page a pending row’s preview link opens: a GitHub check run on the scanned commit, one per pending stack, named sluiceway / <stack id>, that shows that stack’s diff as the summary does. Never a value, and never the tool’s own words. A scan of the same commit updates it in place. Without checks: write there is none, and the link opens the summary. Avoid: Check (that is the pass over the repo’s files), check page, status check, report

Result file: A JSON file that a scan or an apply leaves in the job’s temporary directory for a later step of the workflow, with what its summary holds and nothing more. Sluiceway never sends it anywhere: a step the user adds does, with its own secret. Avoid: Report, artifact, export, metrics

Read-only dashboard: A dashboard drawn with nothing to tick, for a workflow that only scans: pending rows have no box, there is no rescan box, and the line under the Pending heading says so. Set with dashboard.readOnly. It changes what is drawn, not who may deploy: what keeps a workflow from deploying is that it has no resolve job. Avoid: Dry run, view-only mode, preview mode, locked dashboard

Size budget: How large the dashboard body may get before rows are shortened. It exists because an issue body that is too large is dropped without an error. Avoid: Limit, cap, quota

Shortened row: A pending row that shows less than its whole diff because of the size budget, and links to the summary for the rest. It keeps its checkbox, its counts and its warning. Its delete and replace lines are all listed or none are. Avoid: Truncated row, collapsed row, summary row

Attribution: The line on a stack’s row that names the merged pull requests, and the direct pushes, that the stack claims since its last successful deploy from the dashboard. It explains why a row is pending and never decides that it is. Changes the stack does not claim are counted, not named. Avoid: Blame, changelog, history, provenance

Author: The person who opened a pull request that a row names, or who made a direct push. Written as a plain login that notifies no one. An author is never the ticker by role, even when they are the same person. Avoid: Committer, merger, owner, contributor

Direct push: A commit on the default branch that no merged pull request brought there. A row names it by its short commit id and the commit’s author, so it is never left out. Avoid: Unreviewed commit, hotfix, loose commit

Lookback: How many of the newest commits on the default branch a job walks to work out attribution. A stack whose last deploy lies further back gets a line that says earlier changes exist. Avoid: History depth, window, range

Redact: The dashboard setting that keeps resource types, resource names and property names out of the issue, leaving stack ids, counts, warnings and links. The summary stays full. It limits how far names travel. It is not access control. Avoid: Private mode, mask, hide

Destroy: A change whose op is replace or delete: a real object goes away. Destroys are listed first, cut last, and always carry a warning, also on a redacted dashboard. Avoid: Destructive change, dangerous change, removal

Personality

Penny: The mascot: a sluice gate with a face, standing mid-channel in the header. The name is short for penstock. It is used in docs and never on the dashboard. Avoid: The otter, the logo (the logo is Penny without a state), Sluicy

Header: The image at the top of the dashboard, as wide as the issue and centered: Penny on a quay in one header state, in a light and a dark variant. Avoid: Banner, hero, badge

Action ref: The exact release tag of the running action, or its commit SHA. Never a moving tag. The header images are loaded from it and the footer shows it. Avoid: Action version, image tag, release

Header state: Which of six states the header shows: failing, deploying, pending, drift, first run or in sync. The first that applies wins, in that order. It is computed from the row markers and decides nothing. A destroy does not change it. Pending has thirteen pictures, one per crate count, so there are eighteen pictures for six states, and fourteen of them exist once more with the destroy sign. Drift is water seeping through the closed gate. Avoid: Mood, dashboard status, health

Destroy sign: The amber warning triangle on a pole in the water in the header, right of the wordmark. The pending and deploying pictures carry it whenever a pending or deploying row has a destroy. It does not move, and the rest of the picture is unchanged. It is computed from the row markers and decides nothing. It took the place of a grey header state called plain. Avoid: Plain, careful state, warning header, danger state, alarm

Crate count: Which of the thirteen pending pictures the header shows: the number of pending rows, from 1 to 12, or more above 12. It is computed from the row markers and decides nothing. It replaced the pending level. Avoid: Pending level, tier, severity, load

Water step: How high the water stands upstream in a pending picture, one of five: 1 or 2 pending, 3 or 4, 5 to 7, 8 to 10, 11 or more. The gauge on the wall has one amber mark per step. It follows from the crate count. Avoid: Pending level, water level (for the count)

Overflow: The pending picture past the maximum of 12 crates: the row runs on with a half crate cut by the left edge, which reads as more than 12. Avoid: Cap picture, max picture

Upstream and downstream: The two sides of Penny in the header. Upstream is on the left, where water and crates pile up while changes are pending. Downstream is on the right, where water rushes while deploying. Level water on both sides is the picture of in sync. Water always moves left to right. Avoid: Before and after, input and output, left and right side

Crate: A box floating upstream in the header. One crate stands for one pending stack. Up to 12 the picture shows exactly as many crates as there are pending rows, some stacked on two others. Above 12 it shows the overflow. Avoid: Package, box per stack, queue item

Jam: How the failing header state is drawn: the gate stuck half open over a log, with a blinking red lamp. It means something is stuck and needs a person. Avoid: Broken gate, angry gate, crash

Count dot: The coloured dot in front of a count on the counts line: yellow pending, blue deploying, red preview failed and failed deploys, green in sync, white for a count of 0. Shown whenever there is a header. Avoid: Badge, status light, bullet

Voice: Wording with a water image in it. It is allowed in exactly two lines, the good-news line and the first-run line. Everything else Sluiceway writes is plain. Avoid: Tone, copy, humour

Good-news line: The line under the Pending heading when nothing is pending. Avoid: Empty state, all clear message

First-run line: The line under the Pending heading when the scan found no stacks. Avoid: Onboarding message, welcome text

Personality: The header and the voice together. dashboard.personality: false removes both. Avoid: Branding, theme, fun mode