# Read a project's dashboard

A project's page is the Portfolio for one project. This guide walks its header and its **Overview**, **Health** and **Usage** tabs. The other tabs have their own guides: [Costs and budgets](costs-and-budgets.md), [Revenue and profit](revenue-and-profit.md) and [Expiries and the calendar](expiries-and-calendar.md). **Settings** is in [Projects](projects.md#a-projects-settings).

The view bar, the states of a figure, Explain and charts work as on the Portfolio: see [Read the Portfolio](portfolio-dashboard.md).

## Open a project

1. Choose **Projects** in the sidebar (on a phone, **Projects** in the bar at the bottom), or press `g` then `j`.
2. Press the project's name. From the Portfolio, press its row.

The header shows the way back to **Portfolio**, the project's name, its kind and currency ("Commercial · USD") and its surfaces as chips. A domain's chip opens the site and a package's opens its page, each in a new tab.

Owners and admins also see the project's repositories as chips, each opening on GitHub. Its test results, deploys, stars and repository traffic are read from them, so a project with no repository shows none of those. With none, the header has **Link a repository**, which opens [the binding review](review-bindings.md), where a repository is put in a project; while the workspace has no GitHub connection it has **Connect GitHub to see its repositories** instead.

- **Share**, for those who can share it, opens **Settings → Access**.
- The **⋯** button holds **Pin** (**Unpin** when it's pinned), which puts the project first in your Portfolio's table, **Export CSV**, which saves this project's statement as the view bar has it, and **Settings**.

## The tabs

**Overview**, **Health**, **Usage**, **Costs**, **Revenue**, **Obligations** and **Settings**. Some don't always show:

- Without **Can see amounts (revenue, costs, profit)**, there is no **Costs** or **Revenue**. Opening their address gives **Page not found**.
- An open-source or public-good project has **Revenue** only once a revenue source is bound to it.
- A proposed or archived project has no dashboard. It has only **Overview**, **Obligations** and **Settings** (see [Activate a proposed project](projects.md#activate-a-proposed-project)).

On a computer the tabs are numbered, and those numbers are the keys that open them: hold `⌘` (`Ctrl` on Windows and Linux) for a moment to see each tab's number. On a phone the row scrolls sideways.

## Overview

From the top:

1. **Needs you · 2**: what needs you on this project, with **Snooze** and one action each, as on the [Portfolio](portfolio-dashboard.md#needs-you). With nothing to do, it says "Nothing needs you."
2. The statement: **Net profit · 30 days**, **MRR**, **Costs · 30 days**, **Health** and **Next expiry**. **Costs** adds what is the project's alone and what it shares: "$209.92 direct · $69.60 shared". Press a card to explain it.
3. **Revenue and costs**, with this project's deploys in the lane underneath.
4. Three panels, each with its heading as a link to its tab:
   - **Health**: each surface with **OK**, **Degraded**, **Failing** or **No data yet**. With none: "No surfaces yet."
   - **Usage**: the lead metric's latest figure and its **Last 30 days**. With none: "No usage metric yet."
   - **Obligations**: the next three, with the days left. With none: "Nothing coming up."

An open-source or public-good project leads with **Cost to run · 30 days** in place of **Net profit**, and has no **Costs** card beside it: Cost to run is its costs, and the **Costs** tab breaks them down. A project with no **Revenue** tab has no **MRR** card.

An empty card says what would fill it, naming this project. An editor or viewer's **Ask Ana** tells the admins which project asked (see [Ask an admin](projects.md#ask-an-admin)). "Watch a domain to see uptime and renewals." on the **Health** card opens **Settings → Surfaces** for those who can change it.

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)).

## Health

Everyone who sees the project sees **Health**. Press `2`, or the tab.

1. Five cards: **Health**, **Uptime**, **CI**, **Flaky tests** and **Open incidents**. Each explains itself when pressed.
2. **Surfaces**: a row per domain, package or app, with **Uptime**, **TLS**, **CI**, **Tests**, **Lighthouse** and **Release**. A cell has a word as well as a colour: **Passing**, **Failing**, "2 flaky", **Shippable**, **Not yet**. **Project CI** under one means the result belongs to the project's CI rather than to that surface alone. A "—" says what would fill it when you hover, focus or tap it, such as "An uptime check on this address fills this."
3. **Uptime · 90 days**: a strip of days per check, **Up**, **Degraded**, **Down** or **No checks**, with its percentage for the period and **Response time** in **p50** and **p95**. A check that's down today shows on the strip's last cell at once; its percentage waits for a whole day ("No whole day yet · 30 days"), and the **Uptime** card says "Counts from the first whole day". "Checked on 12 of the period's 29 whole days" says when checks started late.
4. **Incidents**: what happened in the period, with **Started**, **Duration**, **Checks affected** and **Resolved by** (such as **Recovered on its own**, **Marked renewed** or **Still open**). A name opens the incident on [Alerts](alerts.md). With none: "No incidents in this period."
5. **CI on main · last 30 runs**: each workflow, "28 of 30 runs passed. The last 2 failed.", with a strip of runs. **Show as table** lists each run's **Result**, **Duration** and **Open run**.
6. **Flaky tests · 14 days**: the tests that failed and then passed on retry, with **Flake rate** and **Last flaked**. With none: "No flaky tests in the last 14 days."
7. **Lighthouse**: **Performance**, **Accessibility**, **Best practices** and **SEO** per page, against each budget. "Performance went from 93 to 84; the budget is 90."
8. **Release gate**: **Shippable** or **Not yet**. **Not yet** says why ("CI on main failing since …", "… is down"); **Shippable** says what it read ("From CI, tests and uptime").

The Portfolio's **Health** has the same cards, with **Projects** in place of **Surfaces**, worst first, **All checks** for uptime, and incidents and flaky tests across projects. Press a project's name to reach its own tab.

On a phone, tables fold into cards.

## Usage

Press `3`, or the tab.

1. **Primary metric**: the metric this project leads with, its change and its source.
2. The chart, titled with the metric and its source: "Daily active users · average · pushed by your app". When two sources measure the same metric, **Compare sources** draws both.
3. **Other metrics**: every other metric with figures, as tiles. A tile says "Through Oct 31" when its source reports late, "No complete day yet" or "Nothing in this period".
4. **Free tiers**: each limit, "90% used, near the limit", "45,000 of 50,000", when it resets and, at the present pace, when it runs out ("At this pace, it reaches its limit by Nov 28 at the latest"). Under them, what a service does at its limit: "Upstash stops serving commands at its Free cap".

Free tiers stay when amounts are hidden: they are usage, not money.

### A project with no usage source

ShipVitals adds no analytics of its own. A project with no source says "… has no usage source." Editors, admins and the owner also read how to fill it:

1. Press **Push your numbers**. **Push metrics for …** opens, with the key and the snippets (see [CI and push metrics](ci-and-push-metrics.md)).
2. Or press **Mark as not tracked** to stop being asked. The tab then says **Not tracked** with **Track usage again**.

Both are also in **Settings → Sources**, under **Usage**.

### Choose what the tab leads with

Editors, admins and the owner:

1. Open **Settings → Sources**.
2. Under **Usage**, choose a **Primary metric**. **By what's available** leaves the choice to ShipVitals.

It saves as you choose. With two sources for one metric, the tab draws the one you chose.

The Portfolio's **Usage** adds a metric across projects when they measure it the same way ("From 1 of 3 projects"), and ends with **Projects with no usage source**, each leading to its own tab.

## Keyboard

| Key        | Does                                    |
| ---------- | --------------------------------------- |
| `1` to `6` | Go to a tab, counting those you have    |
| `p`        | Open the period menu                    |
| `⇧C`       | Turn the comparison on or off           |
| `e`        | Explain the focused card                |
| `s`        | Snooze the focused row of **Needs you** |
| `t`        | Show the focused chart as a table       |

## When it doesn't work

| The page says                      | What to do                                                                 |
| ---------------------------------- | -------------------------------------------------------------------------- |
| **Page not found**                 | You don't have that project or tab. Ask an admin.                          |
| "… wasn't changed. Try again."     | The pin wasn't saved. Try again.                                           |
| "… wasn't exported. Try again."    | The CSV wasn't saved. Try again.                                           |
| "That didn't save. Try again."     | **Mark as not tracked** or the **Primary metric** wasn't saved. Try again. |
| "No usage metric has figures yet." | **Primary metric** has nothing to choose from until a source reports.      |
