Get started

Install the Sluiceway GitHub App. It opens one pull request per repo that adds the workflow and a first sluiceway.yaml, and the console guides you through the rest.

The app is the action, set up for you, with a console. Every deploy still runs in your own GitHub Actions, with your own cloud credentials. The app holds no cloud credential and runs no infrastructure as code. It is free for 5 repos.

1. 1

   You install the app and pick repos

   Install it from github.com/apps/sluiceway on an org or a personal account, for every repo or for a few.

2. 2

   The app opens the onboarding pull request

   On each repo with no dashboard yet: the workflow, a starter sluiceway.yaml, and the secrets each stack needs, by name.

3. 3

   You add the secrets and merge

   Adding the secrets is your step. The first scan then previews every stack and writes the dashboard issue.

4. 4

   You tick a box

   On the dashboard issue or in the console. Your workflow previews the stack again and deploys it.

Install the app

Open the Sluiceway app on GitHub, choose Install, pick the org or account, and choose all repos or only some. You can change the repos later in GitHub’s settings for the installation.

Then sign in at console.sluiceway.dev with GitHub. The console lists every repo of the installation. A repo with no dashboard yet is under Not set up yet, with its onboarding pull request.

Only repos with a dashboard count toward your plan, so installing on a whole org costs nothing. The Free plan covers 5 of them. See Plans and adopted repos.

Merge the onboarding pull request

The pull request is written by the action’s own init and check, so it holds what adding the action by hand would give you:

• The workflow at .github/workflows/deploy-dashboard.yml, which runs sluiceway/sluiceway@v0.
• A starter sluiceway.yaml, or one line added to the one the repo has: sluiceway[bot] in recordWriters, so ticks can go through the app.
• Its description: the stacks the check found, the dashboard the repo would get, and per stack the credentials it needs, as names, with a link to the repo’s Actions secrets settings.

Before you merge, add the secrets it names, or load them another way from Credentials and your own tooling. When your infrastructure cannot be reached from GitHub’s runners, point the workflow at a self-hosted runner.

Then merge. The push of that merge starts the first scan: it previews every stack and writes the dashboard issue with one row per stack. Nothing deploys until someone ticks a box. The console moves the repo from Not set up yet to its stacks, and when the first scan fails it says why in one sentence, with a link to the page that fixes it.

Install the app has the permissions GitHub asks you to accept, everything the pull request holds, and what to do when there is none.

i

Decide who may deploy before you merge

A tick asks for a deploy of that stack, production included. Without a tick rule, anyone with write access to the repo can tick. Narrow it with tickers in sluiceway.yaml, or gate the deploy job with a GitHub Environment. See Who can tick.

Tick

Tick a stack’s box on the dashboard issue, or in the console on the repo’s Dashboard tab. The app picks a tick on the issue up within about a second. A tick in the console holds five seconds first, with an Undo button. The app then judges the tick with the action’s own tick rule, opens the deployment record and starts your workflow. Your runner previews the stack again and deploys only when the change is the one you ticked.

Using the dashboard explains the rows and the boxes, and Using the app the console.

Without the app

The action runs on its own too: the same deploys, with the dashboard issue as the only dashboard. Run the action yourself takes you through it step by step. How the app and the action work together says what the app adds, and what happens to a tick when the app is down.