# Workspaces and projects (https://www.shipfox.io/docs/understand/workspaces-and-projects)

Description: Understand what a team shares in a workspace and what stays with one project.

A **workspace** is the team boundary in Shipfox. It holds the members and the
resources that several projects can use. A **project** connects one repository
to that workspace. It owns the workflows and the run history for that
repository.

The split answers a practical question: what does a team set up once, and what
must stay with one repository? Share what the whole team uses. Keep workflows
and run history with their repository.

## What a slug is for [#what-a-slug-is-for]

Each workspace has a workspace slug that is unique across the installation.
Each project has a project slug that is unique within its workspace. Neither
slug is optional.

The client uses these slugs to build readable URLs such as
`/w/acme/p/checkout-api/runs`. The API still identifies workspaces and projects
by UUID. A slug is for navigation and display. It doesn't replace the identity
of the resource.

Slugs can change. A rename frees the old value and breaks links that still use
the old URL. Shipfox warns before a rename to leave time to update shared
links.

## What the workspace shares [#what-the-workspace-shares]

Many resources serve more than one project: integration connections, model
providers, runners, secrets, variables, and membership. They live in the
workspace, so no repository needs its own copy.

```text
Workspace
|-- Members
|-- Integration connections, model providers, runners, secrets, and variables
`-- Projects
    |-- Project A -> repository A -> workflows and runs
    `-- Project B -> repository B -> workflows and runs
```

The benefit is reuse. The cost is that a change to a shared setting reaches
every project that uses it. A disabled integration connection affects every
project that uses it. A changed model provider does the same. Membership also
grants access to every project in the workspace.

Use separate workspaces when teams must not share members or operational
resources. Use projects inside one workspace when the repositories can share
that administration.

## What the project owns [#what-the-project-owns]

A project records a source integration connection and one repository. Shipfox
reads the workflow files from that repository. Jobs also check it out by
default.

The project also keeps run history separate. Runs for repository A never appear
in project B, even when both projects use the same runner or model provider. A
run keeps its repository identity while it uses shared resources.

## Which scope owns what [#which-scope-owns-what]

The four scopes answer different questions.

| Scope     | Question it answers                                           |
| --------- | ------------------------------------------------------------- |
| Workspace | Which people and reusable resources share one trust boundary? |
| Project   | Which repository owns these workflows and this run history?   |
| Workflow  | Which events and ordered work define this automation?         |
| Run       | What happened for one event or manual start?                  |

Long-lived configuration belongs above the run. Event data, logs, and outputs
belong inside the run that produced them. This keeps one result from becoming
configuration for unrelated future work by accident.

The source integration connection is a special case. It belongs to the
workspace, but the project selects one repository from it. That selection
controls where Shipfox finds workflows and what jobs check out. Other
integration connections can send events or provide agent tools without becoming
the project's source.

Use [Create a project](https://www.shipfox.io/docs/how-to/set-up-work/create-project) for the setup task.
[Integrations, integration connections, and
tools](https://www.shipfox.io/docs/understand/integrations-connections-and-tools) explains the different
roles that an integration connection can play.