Workspace Checks

How Treq runs shell-based check workflows inside a workspace and records pass or fail for each step.

Workspace Checks run the commands you define, such as install, lint, typecheck, and tests, inside a workspace. You write them as YAML workflows in your repository. Each step passes or fails on its exit code, and Treq keeps a run history with the output of every step.

Checks are on in every build. There is no preview switch.

Defining Workflows

Treq reads every .yaml and .yml file in .treq/workflows/ at the root of the repository. A workflow has a name and a set of jobs. Each job has an optional name and a list of steps. Each step has a name and a run command, and may set working-directory and env.

name: CI
jobs:
  verify:
    name: Verify
    steps:
      - name: Install
        run: npm ci
      - name: Typecheck
        run: npm run typecheck
      - name: Unit tests
        run: npm test
        env:
          CI: "true"

A file that is not valid YAML in this shape is skipped. working-directory must be a relative path inside the workspace and cannot contain ... Treq runs each run command with sh -c in the workspace directory.

Running Checks

Checks run against one workspace. You can start them from four places:

• Workspace header. The Checks button shows a summary of the latest runs, such as Checks 2/3, Checks running, or Checks not run. When the branch has a pull request with GitHub checks, the button also shows their count, such as GH 4/5. Click it to open a popover. The Treq checks section lists each workflow with its latest run, such as run #3 passed, and a button that runs or re-runs that workflow. Run all runs every workflow, Setup re-runs the setup script when one is configured, and View logs opens the Logs tab with All checks selected. The GitHub checks section lists the pull request's checks, failed first, and each one opens its run on GitHub. The button is hidden when there are no workflows and no pull request checks.
• Logs tab. With Checks as the log source, the Filter by check menu shows the output of the workflows you tick. With none ticked it shows All checks. The Logs tab does not run checks.
• GitHub panel. Open a pull request whose head branch has a Treq workspace. The Treq checks section lists each workflow and job with its latest status and run buttons. The button next to a job runs that job alone. Open in Logs switches to that workspace's Logs tab with All checks selected.
• Command palette. Run checks… runs every workflow in the current workspace. Run check: followed by a workflow name runs one workflow. Treq shows a notification when the run finishes.

Behavior	Detail
Step order	Steps in a job run one after another. The first failing step stops the job.
Job concurrency	Running a workflow runs up to 4 of its jobs at the same time.
Step timeout	A step that runs longer than 60 seconds is terminated and counts as failed.
Run history	Running a workflow records one history entry. Running a single job records its own entry.
Output	Treq captures stdout and stderr for each step and stores it with the run.

Trusting a Repository

Workflows run arbitrary shell commands from files in the repository. Treq does not run them until you select Trust Repository in the header Checks popover or the GitHub panel, or Trust repository to run checks in the command palette. The trust decision is stored per repository on your machine.

Setup Script

If .treq/config.yaml sets a setup_script, Treq runs it when it creates a workspace. Checks wait until that script has finished. If the script fails, checks can still run. Setup in the header Checks popover, Re-run setup script in the GitHub panel, or the command palette runs it again.

Autosave on Pass

When a run passes and the workspace has uncommitted changes, Treq commits them with a message that starts with treq-autosave: and lists up to two changed files. A failing run commits nothing.

Logs

Check output is stored per run. The Logs tab reads it when the Logs preview is on. Choose Checks as the log source to browse and filter it, or open Logs Explorer to query it with SQL. Filter by check limits the feed and the chart to the runs of the ticked workflows.

Scope

Workspace Checks run on your machine, inside the workspace. They are separate from GitHub Actions and do not replace your CI. For why agent output needs gates like these, see Quality Gates for Agent Output.