Skip to content

Projects

A project groups pipelines that work on the same codebase so they share setup instead of repeating it, along with the triggers that start them and the boards that order their work. Projects are also how the app is organized: the sidebar lists them as a tree, and each project has its own tabs. Projects are optional: a pipeline without a project keeps its own workspace and variables and works exactly the same.

Section (UI) Field What it does
General Name, Color, Description Display only. The name is available to templates as {{project.name}} and to steps as $FACTORY_PROJECT.
Workspace Mode, folder / repository / URL, base branch, branch name template Where the project’s pipelines run. Same options as a pipeline’s workspace; see Workspaces.
Commands Setup, Start, Test, Build, Lint How to set up, run and check the project. Exposed as {{vars.setupCommand}}, {{vars.startCommand}}, {{vars.testCommand}}, {{vars.buildCommand}}, {{vars.lintCommand}}. Empty commands aren’t exposed. See Commands.
Variables key/value pairs Shared {{vars.NAME}} for every pipeline in the project.
Environment key/value pairs Environment variables set for every step of every pipeline in the project. A step’s own env wins. Values are hidden from AI assistants unless you click the eye next to one; see MCP server.
Pipelines list The project’s pipelines, with New pipeline to create one inside it. Pipelines using their own workspace are marked own workspace.

These sections are on the project’s Settings tab.

A project’s commands can come from two places:

  • the Commands fields in the app;
  • a Jimothyfile at the root of the repository, committed with the code.

Commands set in the app win over the Jimothyfile. When the workspace folder has a Jimothyfile, the section says “Uses this folder’s Jimothyfile” and each field shows the file’s command as a greyed placeholder with the hint “From Jimothyfile; type to override”. Otherwise the fields show example placeholders (npm ci, npm run dev, npm test, npm run build, npm run lint) but are empty until you fill them in.

For an Existing folder or Git worktree workspace without a Jimothyfile, two buttons help:

  • Fill in from the files fills empty fields with commands guessed from the repository’s files (package.json, Pipfile, pyproject.toml, Makefile, go.mod, Cargo.toml, *.tf and others). Check what it guessed.
  • Save as Jimothyfile writes the current commands to a Jimothyfile in the folder and clears the fields. Commit the file with the code.

See Jimothyfile for details.

When the workspace is a folder of several repositories, each repository has its own commands. Expand a repository under Workspace → Repositories inside the folder to see them. They work like the project’s: set in the app, or from the repository’s own Jimothyfile, with Fill in from the files and Save as Jimothyfile. Detect fills in guessed commands for repositories without a Jimothyfile.

A shell step that runs in each repository gets that repository’s commands as {{vars.testCommand}} and the rest. For each command, it uses the first of:

  1. the command set on the repository in the app;
  2. the repository’s Jimothyfile;
  3. the project’s Commands.

So the project’s commands are only a fallback for repositories that don’t have their own. In a multi-repo project you can usually leave them blank; the Commands section says so.

  • The + next to Projects in the sidebar, New project in the ⌘K palette, or New project on the all-projects Pipelines list creates a project named New project with an Existing folder workspace and opens its Settings tab. Set the name and workspace, then Save.
  • To create a pipeline inside a project, use the + on the project (or on its Pipelines section) in the sidebar, New pipeline on the project’s Pipelines tab or in its Settings tab, or New pipeline in project in the ⌘K palette. Templates, AI-generated pipelines and imported pipelines are all placed into the project.
  • To move an existing pipeline, open its Pipeline settings and choose the Project. Choosing No project takes it out.

When a pipeline is in a project, its Workspace section shows a Use the project’s workspace toggle, on by default. Turn it off to give that one pipeline its own workspace (for example, a docs pipeline that works in a different repository).

Below Dashboard, Runs and Boards, the sidebar lists your projects as a tree. Each project expands to up to three sections:

  • Pipelines: the project’s pipelines, by name.
  • Boards: the project’s boards (shown when it has any).
  • Triggers: the project’s triggers. Paused triggers are dimmed.

Click the arrow next to a project to expand or collapse it, and the arrow next to a section to fold it (a folded section shows how many items it holds). The + on a project, its Pipelines section or its Triggers section creates a pipeline or trigger in it. Clicking a project opens its Pipelines tab; clicking a section heading opens that tab; clicking an item opens it.

Pipelines, boards and triggers that aren’t in a project are under No project at the bottom.

The tree shows what’s happening right now rather than item counts:

Badge Where Meaning
A number Project, pipeline Runs in progress (queued, preparing or running).
✋ N Project, pipeline Runs waiting for approval. Shown instead of the running count.
3/7 Board A running board: cards done out of those scheduled (Inbox cards don’t count).
Red ! Project One of the project’s triggers is failing. The trigger itself is shown in red.

Opening something inside a project expands that project in the tree. Collapse all projects in the sidebar and Expand all projects in the sidebar in the ⌘K palette do what they say, and the tree can be driven with the arrow keys.

Drag the sidebar’s right edge to make it wider (for long names); double-click the edge to reset it. The width is remembered.

Every page inside a project shows a bar at the top with the project’s name and five tabs:

Tab What it shows
Pipelines The project’s pipelines, with New pipeline.
Triggers The project’s triggers, with Add trigger. New triggers go into the project.
Boards The project’s boards, with New board. New boards go into the project.
Runs Runs of the project’s pipelines. Its count is the runs in progress or waiting for approval.
Settings The project’s settings: the sections described above. Clicking the project name also opens it.

The Pipelines, Triggers, Boards and Runs tabs are the app-wide lists filtered to the project. The lists across every project are still there: All pipelines and All triggers in the ⌘K palette, and Runs and Boards in the sidebar. Each of those lists has a project filter (All projects, No project, or one project).

A trigger can be filed under a project too. It’s for organizing only: the trigger’s Runs pipeline still decides what runs, and that pipeline can be in any project.

  • In the trigger editor, choose the Jimothy project, or No project.
  • Triggers created from a project’s Triggers tab, from the + on its Triggers section in the sidebar, or with New trigger in project in the ⌘K palette go into that project.
  • The Runs pipeline dropdown in the trigger editor groups pipelines by project.

When a run is created, the pipeline is resolved against its project:

  • Workspace: the project’s, unless the pipeline turned off Use the project’s workspace.
  • Variables: the Jimothyfile’s commands first, then project commands, then project variables, then pipeline variables, then per-run overrides. Later sources win for the same name. See Variables & precedence.
  • Environment: project env is applied on top of the global env (Settings → General → Environment variables) and under each step’s own env. See Environment variables.

The pipeline editor’s Variables section shows the inherited values under From project name, with any that the pipeline overrides struck through.

When you create a pipeline from a built-in template inside a project, template variables that the project already provides are dropped. For example, the Feature template’s default testCommand: npm test is removed if the project has a Test command, or if the Jimothyfile at the workspace root has a test command, so that command takes effect instead of being shadowed.

In a project whose workspace is a folder of several repositories:

  • shell steps whose command uses a {{vars.*Command}} variable run in Each changed repository;
  • shell steps that start with git run in Each repository;
  • the template’s command variables, such as testCommand, are dropped, so each repository’s own commands are used.
  • A project can’t be deleted while it still has pipelines: “Still has N pipeline(s) (…). Move or delete them first.”
  • Triggers and boards don’t block deleting a project: they keep working and move to No project.
  • A pipeline, trigger or board can’t be saved into a project that no longer exists.
  • If a pipeline uses the project workspace and that workspace is incomplete (for example no folder chosen), the pipeline editor warns “The project’s workspace isn’t set up yet”, and runs can’t start.
  • Runs record which project the pipeline belonged to when they started.