Checks
Your project's whole CI/CD on your own Mac and free: tests, secret scans, a gate on every push and deployments that only go out green.
Available now. A current user-facing path exists within the stated scope.
What Checks does
Checks runs your project's tests, lint and build on your own Mac, in a clean copy of a saved version, and keeps a signed result you can read later.
It does the job a hosted CI service does, with no service in between. Your files stay on your Mac and your project is never touched, because every run happens in a temporary copy that is removed afterwards.
Open it from Home › Versions › Checks. It sits under With others in the Versions sidebar, next to Team. A run can start by itself after you or an agent change files, or when you choose Run checks now.
Checks needs Versions to be on for the folder, because a run checks a saved version of it. To check a git commit instead, see Run on a commit.
Set up checks in one click
Open Versions › Checks, read the checks Bandicot proposes for your project, and choose Use these checks.
While Bandicot looks at the folder, the page reads Looking at this folder…. It reads the build files at the top of the project and proposes checks from them. Nothing runs yet.
The page lists what it found, such as a package.json, and then each proposed check in the order it will run. Choosing Use these checks saves them in bandicot.checks.json at the top of the project and turns on automatic runs.
If nothing in the folder suggests a check, the page reads No checks yet. Ask an agent Set up checks for this project and it writes the file for you, then you approve it, or write the file yourself as in The checks file.
- Open Home › Versions with the project open and turn Versions on if it is off.
- Choose
Checksin the sidebar. - Read the list of checks under
Check this project on its own. - Choose
Use these checks. The first run starts when the folder has been quiet for a moment, or chooseRun checks now.
| It finds | It proposes |
|---|---|
package.json | deps installs the packages and keeps node_modules. Then typecheck, lint, test and build for each of those scripts the project has. A placeholder test script is skipped. |
Cargo.toml | cargo-build, then cargo-test. |
go.mod | go-vet and go-test. |
pyproject.toml that mentions pytest | pytest. |
Makefile with a check or test target | make-check and make-test. |
If it goes wrong
No checks yet.- Bandicot found no build file it knows. Ask an agent
Set up checks for this project, or write the checks file by hand. The checks could not be set up.- The message under it says what stopped the save. Fix that and choose
Use these checksagain.
The checks file
A project lists its checks in bandicot.checks.json at its root, each with a name, a command, and optionally what must pass first and which folders to keep.
The file travels with your project, and each saved version is checked with the file that version held. Unknown fields are ignored, so a later version of Bandicot can add some.
The file says "schema": 1, 2 or 3. Everything marked below as schema 3 needs that number. It lists checks, each with an id and a run command. Set "auto": false to run checks only when you ask.
A check name is short and made of letters, digits, dashes, dots or underscores. Two checks cannot share a name.
| Field | What it does | Default and limit |
|---|---|---|
schema | The file format. | 1, 2 or 3. |
auto | Whether checks start on their own after the folder has been quiet. | true. |
parallel | How many checks run side by side. | 3, from 1 to 8. |
checks | The list of checks. | At least 1, at most 64. |
id | The name of a check. | Unique in the file. |
run | The command that runs it. | At most 4096 characters. |
timeout_s | Seconds before the check is stopped and marked Timed out. | 600, from 1 to 3600. |
needs | Names of checks that must pass first. | Each must exist in the file. |
cache | Folders inside the project to keep from one run to the next. | At most 8 per check. |
after | Names of checks that must finish first, pass or fail. Schema 3. | Each must exist in the file. |
inputs | File patterns this check reads. If none of them changed and everything it depends on is unchanged, it is not run again. Schema 3. | At most 32 per check. |
retry | How many more times a failed check is tried. A check that needed a retry is counted. Schema 3. | 0, from 0 to 2. |
advisory | A failure is shown and does not hold the commit back. Schema 3. | false. |
requires | Programs the check needs. Without one, it reads Could not run and names it. Schema 3. | At most 8 per check. |
env | Values given to the command. Schema 3. | At most 16 per check. |
always | Runs even when a check before it failed. Schema 3. | false. |
on_commit | Check every new git commit by itself. Schema 3. | Off. |
every_hours | Check again on a schedule. Schema 3. | Off, at most 720. |
push | What a git push does when the commit is not green: block, warn or off. Schema 3. | off. |
report | Shows each commit's result as a bandicot/checks status on GitHub, GitLab or Bitbucket, wherever origin pushes to. Schema 3. | false. |
standards | What the built-in rules leave out: ignore patterns, large_file_mb and dependencies. Schema 3. | 100 MB. |
deploy | Where the project goes out: each with id, run, and optionally on_green, branch and timeout_s. Schema 3. | At most 8. |
If it goes wrong
The checks file cannot be used, followed by a note.- The note says what to fix, such as
Two checks have the same name.orChecks need each other in a circle, so none could start.Fix the file and save it; the page reads it again. - The note says
The file lists more than 64 checks. - Join small checks into one command, or split the project.
- The note says
A time limit must be between 1 and 3600 seconds. - Set
timeout_sinside that range. - The note says
Each cache must be a folder inside the project, such as node_modules. - Use a relative folder path. A path that starts with a slash, climbs out with
..or points at the.gitfolder is refused.
Approving a checks file
Bandicot runs nothing from a checks file it was not told about, so a file that arrived from outside waits for your one tap on Run these checks.
A file you save with Use these checks is approved at the same moment. A file that came some other way, such as a download, a teammate or an agent that wrote it, shows Waiting for your OK with the exact commands it would run. The commands run on this Mac.
Above the history line in Saved versions, a quiet note says the folder lists checks that Bandicot has not been told to run, with See what they run and Run these checks.
The approval is for those exact words. Any later change to the file asks again, so a command cannot be swapped in silently.
If it goes wrong
- Checks never start and the page says
Waiting for your OK. - Read the commands, then choose
Run these checks. That approves this version of the file and starts a run.
Stages and side-by-side runs
Checks that need nothing run first and side by side, and a check that needs others waits until they pass.
A check with no needs is in stage one. Any other check is one stage after the latest check it needs. A run shows the stages as Stage 1, Stage 2 and so on when there is more than one.
Inside a stage, up to parallel checks run at the same time. Three is the default.
If a check fails, every check that needs it is skipped and marked Skipped. That saves the minutes a doomed check would take. A check that does not depend on the failed one still runs.
Only one full run is active on your Mac at a time. Asking for another while one is going says so; start it again when the first ends. Slices are different: they queue and go side by side.
What every pipeline gets by itself
With schema 3, every run also scans for leaked secrets, leftover merge conflicts, oversized files and known bad dependencies, with nothing to set up or pay for.
These rules are built into Bandicot and need no program of yours, except the dependency audit, which uses the tool of your package manager. Their results sit beside your own checks and under Rules on the page.
A check whose inputs did not change is not run again. It shows Already passed and costs nothing. Bandicot only reuses a result when everything that check depends on is reused too, so a stale pass cannot hide behind a fresh failure.
A check that fails and then passes on a retry counts as passed, and the page tells you how many needed one. A check that could not start because a program is missing reads Could not run and names the program, so it never looks like a pass.
| Check | What it stops |
|---|---|
std-secrets | API keys, private keys and tokens in the files of the commit. |
std-conflicts | Files that still hold merge conflict markers. |
std-large-files | A file over the size limit, 100 MB unless you set large_file_mb. |
std-npm-audit std-cargo-audit std-pip-audit std-go-audit | Known vulnerabilities, when the project has that lockfile and the tool is on your Mac. |
If it goes wrong
std-secretsflags a test key that is meant to be there.- Add its folder to
ignoreunderstandards, such asfixtures/**. A real key should be removed and changed. - A check reads
Could not run. - Install the program it names. The commit stays held back until the check really runs, unless the check is
advisory.
The gate on every push
The top of the Checks page says whether the current commit may go out, and with "push": "block" a git push is stopped until it may.
The answer is one of Ready to go out, Held back, Checking or Not checked yet. Under Held back, each reason names the check and what happened to it. Advisory failures are counted and hold nothing back.
A blocking setting installs a small git hook in the project. When you, a teammate on this Mac or an agent pushes, the hook asks Bandicot about the commit, waits for the run if it has not happened, and only lets a green commit leave. A hook someone else wrote is never replaced.
Changing the setting takes effect from Rules on the page, where Stop it, Warn me and Nothing set it. A commit whose checks file you have not approved shows Allow and check instead of running anything.
If it goes wrong
- A push waits a long time.
- The hook is waiting for the checks on that commit. Set
inputson the slow checks so unchanged ones are not run again. - A push says the commit is held back.
- Open Versions › Checks. The reasons name what failed. Fix it, commit and push again.
Run everything againis on the page.- It ignores reused results and runs every check once more, for when you suspect something the inputs do not cover.
Deployments
List where your project goes out under deploy, and Bandicot sends a commit there only when it is green, by your tap or by itself.
Each place appears under Deployments with a Deploy button. It stays off until the commit is green, and asks once more before sending. With on_green set, a green commit on the chosen branch goes out by itself.
The command receives the name of the place in BANDICOT_DEPLOY and the commit in BANDICOT_CHECK_COMMIT. Every attempt is signed and kept, with who started it, so you can see what went out and when.
To go back, choose Roll back beside an earlier good deployment. It sends that commit out again with the same command, after one more tap. A commit that is no longer green cannot be sent.
While a deployment runs, the page reads Deploying to and the place, and Cancel stops it.
Show results on GitHub, GitLab or Bitbucket
Turn on Show results on GitHub under Rules, or set "report": true, and each commit's result appears on the forge as the bandicot/checks status, so a pull request can require it.
Bandicot reads where origin pushes to. GitHub, GitHub Enterprise, GitLab, self-hosted GitLab and Bitbucket are understood; the switch names the one it found.
It posts with the key git already uses for that host: a key saved in Bandicot for the host first, then git's own credential helper. Nothing new is asked for. The key needs permission to set commit statuses.
A commit is only accepted once it is on the forge, so Bandicot keeps trying for up to 45 minutes after the run, the time a push usually takes to follow. The line under the switch says what the forge last answered.
To require it, add bandicot/checks as a required status check in the branch rules of your repository. Then nothing merges until your Mac has passed it.
If it goes wrong
- The line says no key was found.
- Push once from this Mac so git saves a key, or save one in Bandicot under the name
git-<host>.credential. - The line says the forge refused the key.
- Give the token permission to write commit statuses (on GitHub,
Commit statuses: write), then run the checks again.
When checks run
Checks start on their own once the newest saved version has been quiet for a short while, and any time you choose Run checks now.
Automatic runs wait until you and your agents stop changing files, and they never start while an agent is working. After a run ends, Bandicot leaves your Mac alone for a while before the next automatic run.
An automatic run skips a version that was already checked with the same file. With "auto": false the page reads Checks run when you ask, and nothing starts by itself.
Run checks now checks the newest saved version. Run on last commit checks the commit git is on now instead. It shows when the project is a git folder or an earlier run was on a commit.
The commands run on your Mac with the usual setup of your shell, but without the secrets and tokens held in your environment. The CI variable is set, so tools behave as they do on a CI server.
- Open Versions › Checks.
- Choose
Run checks nowto check the newest saved version. - Or choose
Run on last committo check the commit git is on. - Watch the run, as in Live output.
If it goes wrong
The checks could not start.- The detail under the alert says why. Check that the folder has a saved version and that the checks file is valid, then choose
Run checks nowagain. The checks could not be stopped.- The run may already have ended. Wait a moment and read the page again.
Watch a run live
While checks run, each one has its own row with a status, a bar and a clock, and you can open a row to follow its full output as it prints.
The page reads Checking and the name of what is checked: the short commit name, or the version number. The clock at the top counts the run. A bar counts checks done out of all checks.
A row shows one of Waiting, Running, Passed, Failed, Timed out or Skipped. A running row fills its bar toward its time limit. A check that needs others says after and their names.
Select a row that has started to open its output. It follows new output and keeps following while you stay at the bottom. Scroll up to read, and it stops following until you return to the bottom. Colour codes from the program are removed so the text is plain.
Cancel stops the run, and the button reads Stopping… until it has stopped. A stopped run records nothing.
If it goes wrong
- A row reads
Reading…and thenNothing was printed. - The check printed nothing, or its output is no longer kept.
- The output says
The start of a long log is left out. - Only the end of a very long log is shown here. The end is the part that matters when a check fails.
- The output says
Only the end of the output is kept. - The full log of that older run is gone. Bandicot keeps the full logs of the most recent runs and the end of the rest.
Caches between runs
Folders you list under cache, such as node_modules, are kept from one run to the next, but only after a run in which that check passed.
Every run starts in a fresh copy, and files that Versions leaves out, such as installed packages or a .env file, are not in it. Without a cache, a check would install everything again each time.
Before a check runs, a kept folder is moved into the copy, unless the saved version already holds that folder. After the check passes, the folder is moved out again for the next run. A failed check never replaces a good cache.
Compilers and linters key their caches on the path of the folder, so the copy always sits at the same place. The proposed checks already set node_modules as the cache of deps.
If it goes wrong
- A check shows
Failedbut passes in your own terminal. - The check ran in a clean copy, so a file that is left out of versions, such as
node_modulesor.env, is not there. Add a check that installs packages and listnode_modulesundercache. - A check is slow every time.
- Its cache is only saved after a passing run. Fix the failure once, and the next run keeps the cache.
Read the results
The Runs list shows every past run newest first, each with its pass count, duration and age, and a mark appears beside the saved version it checked.
The idle page shows how many checks there are and how many run at a time. A strip of small bars shows the last runs, oldest on the left, green for a pass and red for a fail, with a count such as 5/6 passed. What runs lists the checks in order.
Each row in Runs names what was checked and shows a split bar, a count such as 6/7, how long it took and how long ago. A run made on another teammate's Mac says on another Mac. Select a row to open each check with its time and its output. A failed check opens first.
On the Saved versions line, a version that was checked shows Checks passed or Checks failed. Hover the mark to see how many passed and which checks did not. While a run is going the line shows Checking….
Each result is signed with your Mac's own key and kept beside the history. It is not a version of your files. A result that no longer verifies shows as Unverified, never as a pass or a fail. A run that could not start shows Not checked, with the reason.
When a run ends and you are not on the Checks page, an alert says Checks passed, Checks failed with the names that failed, or Checks could not run. A version that is checked again replaces its earlier result, and Bandicot keeps the newest results for the folder.
| Mark | Meaning |
|---|---|
Checks passed | Every check that ran passed. |
Checks failed | At least one check failed or timed out. |
Unverified | The signed result was changed afterwards, so it is not trusted. |
Not checked | The checks could not run on this version. |
If it goes wrong
- A run reads
Not checkedwith a note that the saved version is too large to copy. - Checks copies the version aside before running it. Narrow the folder Versions keeps, or check a smaller project.
- A run reads
Not checkedwith a note that git could not write out that commit. - Check that git is installed and that the commit exists in this project, then choose
Run on last commitagain.
Run on a commit
Run on last commit checks the commit git is on now, in a clean copy made with git, so you can check exactly what you pushed.
The run is named by the first seven characters of the commit. It reads the checks file that commit holds. Results for a commit are kept like any other.
You need git on the Mac for this. Without it the run reads Not checked.
Run part of a pipeline
A slice runs only the part you name, beside anything else that is running, and it never decides whether a commit may go out.
Name parts of your pipeline in the checks file under pipelines. A name holds a list of checks, or checks and paths together, for example "ui": ["ui-typecheck", "ui-test"]. The Pipelines list in Versions > Checks shows each one with its last result and a Run button.
A slice brings along the checks its own checks need. A slice by path takes the checks whose inputs match that path, and a check that lists no inputs counts for every path. A check that already passed on the same files is served without running again, so a full run afterwards only does what is left.
Slices go side by side, as many as your Resources setting leaves room for, and the rest wait their turn. Only a full run can turn a commit green.
If it goes wrong
- A pipeline answers that no check matches.
- Its paths touch no check's
inputs. Add the folder to a check'sinputs, or name the checks directly.
How agents run checks
An agent can start your whole pipeline or any part of it with one call, wait for it and read each pass or fail back, so it never has to ask you to run a check for it.
The agent runs the approved checks in a clean copy, the same way you do, and gets the result for each check with the output of the ones that failed. It can also list the checks or read an earlier run without starting a new one. A checks file that changed since you approved it waits for your one tap first.
With the program tool an agent runs many parts at once, across every project open in Bandicot and in its own machine. Parts it runs in a machine use only the programs installed there. An agent can save a named pipeline without asking you, because a name can only list checks that already exist. Only the checks file adds a command, and a changed file still waits for your one tap.
An agent's terminal runs inside a sandbox. Checks that make scratch folders in the Mac's temporary folders work in the sandbox. When the sandbox stops a command, the agent runs it again itself, and you get one tap to allow it. The Reach outside the workspace switch in Settings also opens the temporary scratch folders to the agent's terminal.
Every commit an agent makes ends with two lines Bandicot writes itself: Co-Authored-By: Bandicot <noreply@bandicot.app> and Bandicot-Session: with the agent's id, so the history says which agent wrote what. Run git config bandicot.attribution false in a project to leave them out there.
See Approvals for how a request to leave the sandbox reaches you.
If it goes wrong
- An agent says the sandbox stopped a check.
- Allow the one tap it asks for, or turn on
Reach outside the workspacein Settings. The agent then runs the check again.
When checks do not behave
Most trouble is a checks file Bandicot cannot read, a command that needs a file Versions leaves out, or a run waiting for your approval.
Start at the Checks page. It says which of those it is: The checks file cannot be used, Waiting for your OK, or a failed row you can open.
If it goes wrong
- The Checks page is empty or reads
Not set up yet. - Versions must be on for the folder first. Then follow Set up checks in one click.
- The mark never appears beside a version.
- The version may not have been checked yet. Choose
Run checks now, or confirm that automatic runs are on and the folder has been quiet. - A result shows
Unverified. - The stored result was changed after it was signed. Run the checks again for a fresh result.
- A check hangs and then reads
Timed out. - Raise its
timeout_sin the checks file, or look at its output to see what it waits for.
Questions
Is Checks a CI service?
It does the job of one, with no service in between. Nothing is uploaded and no one else's computer runs your tests. Checks runs the commands in your checks file on your own Mac, in a clean copy of a saved version.
Does it cost anything?
No. Checks runs on your own Mac, so there are no minutes to buy and no limit on the projects you use it with.
Can it replace GitHub Actions?
For most projects, yes: stages, caches, retries, secret scans, a gate on every push, deployments with roll back, and a bandicot/checks status on GitHub that branch rules can require. It builds for the machine it runs on; an agent can run a slice inside its own Linux machine, and a job that must run on Windows needs a Windows machine.
Does it work when GitHub is down?
Yes. Runs, the push gate and deployments happen on your Mac. Only the status shown on GitHub waits, and it is posted once GitHub answers again.
How do I see which agent made a commit?
Each agent commit ends with a Bandicot-Session line naming the agent. git log shows it, and so does any forge.
Can Bandicot stop a push that is not green?
Yes. Set "push": "block" in the checks file, or choose Stop it under Rules on the Checks page.
Does a run change my project?
No. Each run happens in a temporary copy that is removed afterwards. Only the signed result is kept.
Where do I turn it on?
Open Home › Versions › Checks and choose Use these checks, or ask an agent Set up checks for this project. Versions must be on for the folder.
Can an agent run my checks?
Yes. It starts them in a clean copy, waits and reads each result back, including the output of any that failed. A checks file you have not approved waits for your one tap.
Why does a check fail here but pass in my terminal?
Checks runs in a clean copy, so files that Versions leaves out, such as node_modules or .env, are not there. Add a check that installs packages and keep the folder with cache.
Can I stop a run?
Yes. Choose Cancel on the live page. A stopped run records nothing.
Can I check a git commit?
Yes. Choose Run on last commit to check the commit git is on now. It needs git on your Mac.
Do my secrets reach the checks?
The commands run with the usual setup of your shell, but without the secrets and tokens held in your environment.