# Projects

A project is one thing you run: an app, a website, a library. ShipVitals proposes projects from what your connections find (a product you sell, a Firebase project, a repo another connection points at), and you can make one by hand. A GitHub repo on its own never becomes a project: you put the ones you run in a project. Each project page is a dashboard of its own, with its settings: what it's reached by, what feeds it, its budgets, who can see it and what it publishes.

Everyone in a workspace sees the projects they have access to. What you can change depends on your role:

- **Owner** and **Admin**: everything, including **New project**, **Activate**, **Archive**, **Delete project** and the links into Connections.
- **Editor**: changes their projects (**Edit**, **Surfaces**, **Budgets**) and can share them with viewers.
- **Viewer**: sees their projects' **Overview**, **Health**, **Usage**, **Obligations**, **Sources** and **Access**, and **Costs** and **Revenue** with **Can see amounts (revenue, costs, profit)**.

Without **Can see amounts (revenue, costs, profit)** on your access, money figures show as "—" and the page says **Amounts hidden**.

## The projects list

In the sidebar, choose **Projects** (on a phone, it's in the bottom bar). Or press `g` then `j`.

Each project shows its kind (**Commercial**, **Open source**, **Public good** or **Client-funded**), its **Sources** (or "Nothing bound yet"), its surfaces ("2 surfaces") and its **MRR**. Owners and admins also see a row of pillars, **Revenue**, **Costs**, **Health**, **Usage** and **Obligations**, each with an icon for covered, partly covered or not connected (a pillar that isn't connected is muted).

Owners and admins also see **Not active yet**: projects ShipVitals suggested from your connections, or that the plan had no room for, each with its name and kind ("… Nothing reads their data until they're active."). A project you make yourself in the binding review is active at once and isn't listed here. When a connection proposed any of them, **Review and confirm** opens the binding review (see [Review bindings](review-bindings.md) and [Activate a proposed project](#activate-a-proposed-project)).

### Repos that aren't in a project

Connecting GitHub doesn't make a project for every repo: most accounts have many more repos than things they run. Owners and admins see a card on **Projects** instead, such as "34 repos aren't in a project", with "A repo doesn't become a project on its own. Put the ones you run in a project; the rest can stay as they are."

- Press **Choose repos**. The binding review opens, with the repos under **Not matched** (see [Review bindings](review-bindings.md)).
- On a repo's row, choose the project it belongs to, or **Create project** to make one from it, or **Ignore**. Then press **Confirm … bindings**.
- A repo that looks like part of a project you already have is named on the card ("… looks like part of …"): its homepage, or a domain found in it, is one of that project's domains, or it has the project's name. It waits in the review as **Needs a look**; press **Accept** there, or move it.

A repo does get a proposed project when another connection points at it: a hosting project that deploys it, a Firebase project named in it, a Sentry project of its name. Repos left out of every project ask for nothing: they aren't counted as waiting for review.

At the end, **Archived** lists the archived projects you have access to (everyone sees these): projects nothing new is read for.

If you see only some projects, the line under **Projects** says so ("3 of 12 projects"; "· amounts hidden" when none of yours shows amounts). The others are counted, never named.

With no projects yet, the page says **No projects yet**: "Connecting your services proposes them: a product you sell, a Firebase project, a repo something else you connected points at. Or make one with New project.", with **Connect a service**, which opens **Connections**.

## Make a project

Owners and admins only.

1. On **Projects**, press **New project**.
2. Type a **Name**.
3. Choose a **Kind**.
4. Choose a **Currency** ("This project's own figures are shown in it."). It starts as the workspace's.
5. Press **Create project**. The project's page opens, its **Overview** saying what would fill it.

If your plan has no room for another project, it's created as proposed: the toast says "… is created. …" with the plan's line, and it's listed under **Not active yet**.

To change these three later, open the project's **Settings**, which opens on **General**, and press **Edit** under **Name, kind and currency** (editors too). Change them in **Edit …** and press **Save**.

## A project's page

Press a project's name. The page shows its name, kind and currency, its surfaces as chips, and the tabs **Overview**, **Health**, **Usage**, **Costs**, **Revenue**, **Obligations** and **Settings**. Without amounts there is no **Costs** or **Revenue**, and an open-source or public-good project has **Revenue** only once a revenue source is bound to it. A tab you don't have gives **Page not found**. On a phone the tabs scroll sideways, with the one you're on brought into view.

**Share** (for those who can share it) opens **Settings → Access**. The **⋯** button holds **Pin**, **Export CSV** and **Settings**.

The tabs have their own guides:

- **Overview**, **Health** and **Usage**: [Read a project's dashboard](project-dashboard.md).
- **Costs**: [Costs and budgets](costs-and-budgets.md).
- **Revenue**: [Revenue and profit](revenue-and-profit.md).
- **Obligations**: [Expiries and the calendar](expiries-and-calendar.md).

An empty figure says what would fill it. For owners and admins, that's the step, such as "Connect Stripe to see MRR." or **Review bindings** (see [Review bindings](review-bindings.md)). For editors and viewers, it says who can connect it, with **Ask an admin** (see [Ask an admin](#ask-an-admin)).

For owners and admins, a project with a GitHub repo and no test results yet says "No test results yet from …." with **Set up CI** (see [CI and push metrics](ci-and-push-metrics.md)).

## A proposed or archived project's Overview

A proposed or archived project has no dashboard, so its only tabs are **Overview**, **Obligations** and **Settings**. Its **Overview** keeps the first numbers, four rows in the project's own currency:

- **Revenue · 30 days**, gross and net.
- **MRR**.
- **Costs · 30 days**.
- **Site health**: **Up** or "1 check down", "TLS 41 days left", "example.com until …".

A row with nothing known shows "—", never 0, with a line on what would fill it. For owners and admins, that line has the step: **Connect** and the service that fills it (**Connect Stripe**, **Connect Google Cloud**), **Connect a service**, **Review bindings** or **Add a domain**. For editors and viewers, it says who can connect it, with **Ask an admin**.

While older history loads, a row says "Backfilling older history · through 2025-03".

## A project's settings

Press **Settings** in the tabs, or **Settings** under **⋯**. Its sections are listed beside the page on a computer and in a row above it on a phone: **General**, **Surfaces**, **Sources**, **Budgets**, **Access** and **Public**. Viewers have **Sources** and **Access**, and **Settings** opens on the first section you have. **General** holds what acts on the project itself, for those who can use it: **Edit**, **Archive** and **Delete project**.

### Surfaces

Editors, admins and the owner. What people reach the project by: its domains, npm packages, apps and Firebase projects, each with where it came from ("Found in …", "Found by a connection", "Added by hand") and a domain's **Checks** (**OK**, **Warning**, **Failing** or **Not checked yet**).

To watch a domain:

1. Press **Add a domain**. A form opens under the section's heading; **Close** puts it away.
2. Type the **Domain** ("Like example.com, without https:// or a path.").
3. Leave **Check uptime** and **Watch the certificate and the registration** ticked, or untick either.
4. Press **Add a domain**. The page says "example.com is watched with 2 checks." A domain already watched says "example.com is already watched.", and with neither box ticked no check is added.

Press the remove button beside a surface to take it off the project: "… is no longer a surface of this project."

### Sources

What feeds the project's figures: each resource bound to it, and the share it takes ("All of it", or "50% share"). Owners and admins also see which connection reads it ("Read by …", which opens the connection) and **Open the binding review**.

Editors, admins and the owner also have **Usage** here: the **Primary metric** and **Mark as not tracked** (see [Read a project's dashboard](project-dashboard.md#usage)).

### Budgets

Editors, admins and the owner, with amounts. A monthly or yearly limit on what the project spends, in total or with one provider.

1. Under **Add a budget**, type the **Amount** in the project's currency.
2. Choose **Monthly** or **Yearly** under **Period**.
3. Choose a **Provider**, or leave it empty for **All spending**.
4. Press **Add a budget**. The page says "Budgets are saved."

Without amounts, the section says "Your access to this project doesn't include amounts, so its budgets aren't shown."

**Cost classes** under the budgets sets what counts as variable or fixed (see [Costs and budgets](costs-and-budgets.md#cost-classes)).

### Access

Who sees the project, with their role, how (**Given this project**, **Sees all projects** or **Sees the whole workspace**) and **Amounts shown** or **Amounts hidden**, plus open invitations ("Invited as viewer · expires …"). A viewer reads "Ask an admin who else sees this project." instead.

To share the project:

1. Press **Share**, or open **Settings → Access**.
2. Under **Share …**, type one or more **Email addresses** (up to 20).
3. Choose a **Role**, **Viewer** or **Editor**, when you can give either. Editors can invite viewers only.
4. Tick **Can see amounts (revenue, costs, profit)** if they should (only if you see amounts yourself).
5. Check the summary ("1 person will see …, without amounts, as a viewer. The invitation expires in 7 days.") and press **Send invitation** (**Send 3 invitations** for several).

The page says "Invitation sent to …." For people who couldn't be invited it says why ("Not sent to …: no free seat"). See [Invite people](invite-people.md) for invitations to the whole workspace.

### Public

Editors, admins and the owner. The project's status page and verified MRR badge: see [The status page and badge](status-page-and-badge.md).

## Activate a proposed project

A proposed project's **Overview** says "This project isn't active yet, so nothing reads its data." Its empty rows say "Shows once you confirm this project in the binding review." with **Review bindings**.

Owners and admins: for a project you created (proposed because the plan was full), press **Activate**. The page says "… is active." If your plan is still full, the page says so. A project proposed from what a connection found is confirmed in the review instead: its page says "Discovery proposed this project: confirm it in the binding review." with **Open the binding review** (see [Review bindings](review-bindings.md)).

## Archive a project

Owners and admins only.

1. On the project's **Settings**, under **General**, press **Archive**.
2. The page asks "Archive …?": "Its history is kept; nothing new is read for it." Press **Archive** to confirm, or **Cancel**.
3. The page says "… is archived." with **Undo** for 10 seconds. It moves to **Archived** on the projects list and no longer counts on your plan.

To bring it back later, open the archived project's **Settings** and press **Unarchive**: "… is active again.", or, when your plan has no room for it, "… is back, waiting as proposed." If archiving fails, the page says "… wasn't archived. Try again."

## Delete a project

Owners and admins only. Deleting can't be undone; to keep a project's history, archive it instead.

1. On the project's **Settings**, under **General**, press **Delete project**.
2. The page asks "Delete …?" and says what goes and what stays: its surfaces and their checks, its budgets, its bindings and everyone's access to it are deleted, and an invitation only to it is withdrawn; the revenue, costs, subscriptions and obligations its connections brought stay in the workspace, bound to no project. Press **Delete project** to confirm, or **Cancel**.
3. The projects list opens and says "… is deleted."

A resource it shared with other projects is split again among the projects left. If deleting fails, the page says "… wasn't deleted. Try again."

## Ask an admin

Editors and viewers can't connect services. Where a number is missing, the Portfolio and the project's dashboard say who can connect it, for example "Costs aren't connected yet. Ana (admin) can connect them."

1. Press **Ask Ana** (or **Ask an admin** when no admin is named).
2. The page says "Sent to Ana's notifications." The admins get one notice in their bell: "… asked for costs on …" when you asked from a project's Overview, or "… asked for costs in …" (the workspace) when you asked from the Portfolio. The notice names you by the **Name** in [Account settings](account-settings.md); without one it says "Someone asked …", since a notice never carries an email address.

You can ask once a day for each kind of number. Asking again the same day says "You asked today. The admins have it in their notifications."

An admin who presses the notice lands in Connections on the service that would fill it.

## The Portfolio

The Portfolio (`g` then `p`) shows every project you see: what needs you, the statement's cards, a chart and a table of projects. See [Read the Portfolio](portfolio-dashboard.md).

Owners and admins see the next thing to connect in gold while a figure has nothing behind it. An empty card says what fills it: a step such as "Connect Stripe to see MRR.", or, when a connection brings it in with nothing bound yet, "A connection brings this in, but nothing of it is bound to a project yet." with **Review bindings**. If you see only some projects, the line under the workspace's name says so ("1 of 2 projects"), and each empty card offers **Ask an admin** as above.

## When it doesn't work

| The page says | What to do |
|---|---|
| **Page not found** | You don't have access to that project or section. Ask an admin. |
| "Enter a name of up to 200 characters." | Give the project a name. |
| "Enter an amount of 0 or more, like 1500.50." | Type the budget as a number. |
| "The amounts are in a currency without an exchange rate yet. They show once the rate is in." | Nothing to do; the figures appear once the rate is in. |
| "That didn't send. Try again." | Check your connection and press **Ask …** again. |
| "That didn't save. Check your connection and try again." | Check your connection and try again. |
