Projects
A project groups pipelines that work on the same codebase so they share setup instead of repeating it. Projects are optional: a pipeline without a project keeps its own workspace and variables and works exactly the same.
What a project holds
Section titled “What a project holds”| 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. |
| 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. |
| Pipelines | list | The project’s pipelines, with New pipeline to create one inside it. Pipelines using their own workspace are marked own workspace. |
The command fields show placeholders (npm ci, npm run dev, npm test, npm run build, npm run lint), but they’re empty until you fill them in.
Creating and using projects
Section titled “Creating and using projects”- Pipelines → New project (or the + next to Projects in the sidebar) creates a project named New project with an Existing folder workspace and opens its settings. Set the name and workspace, then Save.
- To create a pipeline inside a project, use Pipeline on the project’s header in the Pipelines list, New pipeline in the project’s settings, or the + on the project in the sidebar. 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).
How project settings merge into a run
Section titled “How project settings merge into a run”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: project commands first, 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) 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.
Templates inside a project
Section titled “Templates inside a project”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, so the project’s command takes effect instead of being shadowed.
Rules and limits
Section titled “Rules and limits”- A project can’t be deleted while it still has pipelines: “Still has N pipeline(s) (…). Move or delete them first.”
- A pipeline 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.