Using the app

The app draws what your dashboards say, across every repo it covers, in the dashboard’s own words. Every row it draws leads back to its repo and its dashboard on GitHub.

Sign in at console.sluiceway.dev with GitHub. The app reads which installations and repos you may see when you sign in, and keeps no token of yours. A session lasts 30 days from the last day you used it. While you use it, the app asks GitHub again every hour, so a change of your membership on GitHub shows within the hour.

The top bar shows where you are, an org or one of its repos, and switches between them. An org has the tabs Overview, Insights, Audit and Settings. A repo has Dashboard, Insights and Audit.

The org view

The org’s Overview tab is every stack of every repo the app covers, at console.sluiceway.dev/<org>.

• The counts of the five states, pending, deploying, drifted, preview failed and in sync, and when the last scan ran. Queued stacks count as deploying, and their rows still say queued.
• One banner naming every pending stack that deletes or replaces resources.
• Chips that filter the rows by state.
• The groups: Needs you (pending, drifted, preview failed), In flight (deploying) and In sync, folded. Or By repo, one panel per repo.

A row is one link to its repo. It says what the dashboard’s row says, without the changes: the state, how many resources it deletes or replaces, drift outside the code, and how the stack’s last deploy ended, with who ticked it or merged it. A deploy the dashboard’s trail lists as an outside deploy is marked “deployed outside the dashboard”, with its short commit, and names nobody.

Under the stacks:

• Not set up yet: repos with no dashboard, each with its onboarding pull request or the button to ask for one, and why a first scan failed when it did. See Install the app.
• No stacks found: one quiet line for the repos where init found no stack.
• Past the free tier, or past your plan: adopted repos beyond your plan’s number, greyed out. See Plans and adopted repos.

A repo’s dashboard

The Dashboard tab is the repo’s dashboard issue drawn again, in the same order, with the same headings and sentences, Penny’s header included. The app draws it with the action’s own renderer, from the facts it keeps. It carries a release of the action of its own, which can be older than the one these docs describe, so a sentence that a newer release words differently reads in the console as that older release wrote it.

The app keeps no diff, so a pending or drifted row is drawn the way a redacted row is: its counts and no change lines. The changes themselves are one click away on the dashboard on GitHub. A failure line points at the run, since the app keeps no reason.

Tick from the app

On a repo whose sluiceway.yaml names sluiceway[bot] in recordWriters, a box on the Dashboard tab is a real box. Tick it, and:

1. The row holds for five seconds, dimmed, and a toast says “Asked GitHub to deploy” with the stack id and an Undo button. Undo takes the tick back, and nothing was asked of GitHub.
2. The app judges the tick with the action’s own tick rule and your permission on the repo, read live from GitHub, exactly as your workflow judges a tick on the issue.
3. An allowed tick starts your workflow and opens the stack’s deployment record with you as the ticker. The row says “asking GitHub to start the run…”, then waiting to start. Undo still works until the record is open.
4. Your runner deploys. The run previews the stack again and deploys only when the fresh preview gives the same diff hash, as for any tick. The row moves as the dashboard’s row does.

A refused tick writes nothing on the issue. The refusal, in the action’s own words, comes back to you on the page.

The app never says a deploy went out: it says what it asked GitHub for. GitHub and your runner decide the rest, and the row shows it.

Some boxes stay on GitHub, drawn as the same square but linking to the dashboard there:

• the bulk, confirm and merge boxes, and the rescan box of the issue;
• a drift repair, and a stack with a dependency, a phase, a deploy window or deploy on merge, or one an ignore entry leaves out;
• every box on a repo that does not name the app in recordWriters. The tab then shows one line with a button that opens the pull request to add it.

A read-only dashboard has no boxes, in the app or on GitHub.

Ticking and Rescan from the app work in a repo whose sluiceway.yaml names sluiceway[bot] in recordWriters. In any other repo a box opens the dashboard on GitHub, and the rescan box is there too.

You can also tick and rescan from a terminal, or have a coding agent do it with a token you make: the command line asks the app, which judges it by the same rules.

Rescan

Rescan in the top bar asks for a full scan: of the repo in view, or from the org, of one repo or every repo the app scans. It follows the rule of the rescan box: you need write access to the repo.

The app starts your workflow, which runs a full scan, and the rescan box on the issue stays unticked. A rescan deploys nothing, so it is asked at once, with no Undo. The toast says “Asked GitHub to scan” and the repo’s name. Asking again while that scan runs starts nothing new.

The button is drawn only where the app can ask for the scan. A repo that does not name the app in recordWriters, and one past your plan, has no Rescan on its own pages: its rescan box is on its dashboard on GitHub. The org’s Rescan menu lists every adopted repo, one that the app scans as “Rescans here” and any other as “Rescan on GitHub”, which is a link to that dashboard.

Insights

Insights, for an org or for one repo, cover a window you choose: 12 weeks, and 6 months or 1 year where your plan’s history covers them. Weeks start on Monday in UTC, and each number is set against the same span before it. On Free the app keeps 30 days of history, so only the last weeks have their numbers.

• Lead time: from the merge of a pull request to the deploy of its merge commit, the median. A deploy of a commit with no merged pull request, such as a direct push, is not measured.
• Deploys per week, from the dashboard and outside it.
• Change failure rate: failed deploys from the dashboard over all deploys from the dashboard.
• Deployed outside the dashboard: the outside deploys a full scan found.

Four charts show lead time per week, deploys per week, stacks drifted per week, and where the time goes between a merge and its deploy: to the scan, to the preview, waiting for a tick, and the deploy itself. The org’s Insights end with a table of the repos that had deploys in the window, and one sentence that names the repos with none.

A number the facts cannot give says “Not measured yet” in one sentence, with no number.

The audit log

The Audit tab lists one line per deploy, newest first: when, the repo, the stack, who ticked or who merged, the commit, and the result in the trail’s words. A deploy outside the dashboard is flagged in bold after its result, “⚠ outside the dashboard”, and names nobody, because the tool’s history never says who.

A tick from the command line counts as the person whose token it used, and its line says “via the command line”.

The buttons above the log filter it: every deploy, the flagged lines only, and from the org, one repo. There is no button for one stack: add ?stack= and the stack id to the address. Every filter is part of the address, so a filtered log can be pasted into a ticket. Download CSV downloads what the page shows, with the same filters, the time in UTC and the whole commit.

The log shows one month at a time, the newest first, with Older and Newer under it. It goes back as far as your plan’s history, and its last sentence says how far. What is older than that is deleted each night: see How long it keeps it.

Edit mode

Customise on the Dashboard tab turns the dashboard into its own editor: the same render, with the settings of the block you select beside it. Every change redraws the dashboard and the diff of sluiceway.yaml.

Every setting is a documented key of sluiceway.yaml that the action reads without the app. What you build keeps working exactly the same if you stop using the app.

Select a block of the dashboard, and its own settings open:

• Header picture: personality, Penny’s header and voice.
• Title and Counts line: dashboard.title, and whether a count of 0 is shown.
• A section: drag it to move it, and turn it on or off where the action has a key for that. Pending and Preview failed cannot be hidden.
• Pending: Row detail, which is how much a pending row shows, the Caution that names destroys, the Deploy all box, and showValues.
• Drifted: the Repair all box.
• In sync: the ignore list with its reasons.
• Recently deployed: recentlyDeployed and timeZone.
• Rescan box and Footer: each on or off.

Under The whole dashboard are the settings that belong to no block:

• The dashboard: dashboard.title, redact, readOnly and drift.enabled.
• Templates, below.
• Who may tick: tickers, and recordWriters as the app on the list or off it.
• Stacks: per stack, deploy and tickers.

A setting at its default takes its key out of the file. See Configuration for what each key does.

Templates

A template is a named set of those keys, applied in one click over the settings you have, and adjusted after. It touches no key it does not name.

• Minimal: personality off, a pending row cut to its first line and what must be seen, the In sync section off, no count of 0, and the last 3 deploys in the trail.
• Classic: every dashboard key, the layout and drift at the action’s defaults.
• Ops desk: the last 30 deploys in the trail, drift on, every line of a pending row and every count. Set your time zone yourself.

No template turns redact on. To keep resource names and values off the issue, set Redact yourself, under The dashboard.

A change is a pull request

A bar above the dashboard counts your changes, with Discard and Review pull request. Review shows the pull request before it exists: its title, its branch, sluiceway/dashboard, and the diff of sluiceway.yaml. Open the pull request then opens it, from the commit the dashboard was scanned at. It changes sluiceway.yaml and nothing else, keeps every other key and every comment as they were, and its description names each change and shows the dashboard as it will look. A person merges it, and the next scan draws the dashboard that way.

The app never changes the file behind anyone’s back. While a pull request from edit mode is open, the app names it rather than open a second one. When the file moved on the default branch since the scan, the pull request shows the conflict for you to resolve.

On a repo with no dashboard yet, edit mode starts from the action’s example dashboard.

Settings

The org’s Settings tab holds what the app decides, and nothing that belongs in sluiceway.yaml:

• Plan: your plan, its repos and history, and billing. See Plans and adopted repos.
• Active repos: which adopted repos your plan shows.
• The installation: the repos the app is installed on, with a link to GitHub’s page to change them.
• The app’s access: whether each adopted repo names the app in recordWriters, with a button that opens the pull request to add it or take it out.
• Second approver: what your plan does with the Sluiceway protection rule, and who may approve. See Plans and adopted repos.
• Delete everything, last and apart: an admin of the org, or the person whose account it is, deletes all the app keeps of the installation at once. See If you stop using the app.