Skip to main content

Projects

A project is a team scope inside a workspace. Where a workspace is the security and billing boundary (the customer), a project is the naming, scoping, and navigation boundary underneath it: a team, a product line, or however you want to split up the repositories and automation inside one workspace.

The hierarchy is:

workspace → project → repository → service

Every repository belongs to exactly one project. Everything that hangs off a repository (its builds and services) reaches its project by following the repository, so those rows never carry a project of their own.

What's inside a project​

  • Repositories: every repository you connect belongs to exactly one project. This is required: there's no such thing as a repository with no project.
  • Builds & services: scoped implicitly, through their repository. You don't assign these directly.
  • Triggers: most triggers are scoped through the repository they listen to. A trigger with no repository (a manual or generic-webhook trigger with inline pipeline YAML) is scoped to the project directly, since it has no repository to inherit one from.
  • Variables: repository-scoped and trigger-scoped variables reach their project through that repository or trigger. A workspace-level (org-scoped) variable (one with no repository and no trigger) can optionally belong to a project, to scope a team-wide variable to that team instead of the whole workspace.

Members, billing, and workspace-wide settings stay at the workspace level. Projects don't have their own members list or plan; every project in a workspace is visible to everyone who's a member of that workspace.

The default-project invariant​

Every workspace always has at least one project. When a workspace is created, a project with the slug default is created for it automatically: you never start with zero projects, and there's no path that lets a workspace end up with none. If you never create another project, default is where every repository you connect lands.

Creating and switching projects​

The project switcher sits next to the workspace switcher at the top of the dashboard:

  • With exactly one project, it shows as a static label: there's nothing to switch between yet.
  • With more than one, it becomes a dropdown listing every project in the workspace, with the current one marked.
  • The + button next to it is where you create a new project, from any screen.

Switching projects keeps you in the same section: from Triggers in one project, switching lands you on Triggers in the new one, not back at the home screen. A detail page (a specific build or trigger) collapses to that section's list instead, since a build or trigger id from one project doesn't exist in another.

You can also see every project in the workspace (and create one) from the Projects list (/<workspace>/~).

Creating a project​

Give it a name (display-only, editable later) and a slug (URL-safe, permanent). A new project starts empty: it owns no repositories yet, so connecting one is the first useful step.

Slug is permanent

A project's slug appears in every bookmarkable URL under it. It cannot be changed after creation. Only the display name can. Pick something short and stable.

A project can be deleted from Settings → General, but only once it owns no repositories. The request is refused rather than cascading into their triggers and build history. Move or disconnect the repositories first. See Working with projects.

For workspace staff

Super-admins manage a workspace's projects (create, rename, see the default-project badge) from the Projects tab on that workspace's detail page in the admin console. These are the same create/rename operations available to workspace members, on the governance surface.