> For the complete documentation index, see [llms.txt](https://docs.flash.im/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flash.im/docs/sample.md).

# sample

\---------------

This quickstart gets you to your first deploy as fast as possible. We'll skip most of the configuration — you can refine things later once you have something running.

{% hint style="success" %}
**Estimated time: 5 minutes.** All you need is an account and a project to deploy.
{% endhint %}

## Steps

{% stepper %}
{% step %}

#### Create your workspace

Sign in and create a new workspace. The workspace name appears in URLs and email notifications, so pick something recognisable.

```
yourcompany
```

{% endstep %}

{% step %}

#### Connect a source

Link a repository from your version control provider, or upload a project directly.

{% tabs %}
{% tab title="Repository" %}
Click **Connect repository**, authenticate with your provider, and select the repository to import. The platform will detect your framework automatically.
{% endtab %}

{% tab title="Upload" %}
Drag and drop a project folder, or use the CLI:

```bash
platform deploy ./my-project
```

{% endtab %}

{% tab title="Template" %}
Browse the template gallery and click **Use template**. A new project will be created from the template in your workspace.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Configure your build

Most projects work with the auto-detected settings. If yours doesn't, override them in **Project settings → Build**.

```yaml
build:
  command: npm run build
  output: dist/
  node: 20
```

{% endstep %}

{% step %}

#### Deploy

Hit **Deploy**. Your project will build and go live at a generated subdomain. You can promote it to production or add a custom domain at any time.

{% hint style="info" %}
First builds typically take 1–3 minutes. Subsequent builds are faster because dependencies are cached.
{% endhint %}
{% endstep %}
{% endstepper %}

## What's next?

You've shipped something — now make it yours.

{% content-ref url="/pages/56a52747d54863f8df67ff3ce908938888c69b66" %}
[Broken mention](broken://pages/56a52747d54863f8df67ff3ce908938888c69b66)
{% endcontent-ref %}

{% content-ref url="/pages/fb922e107b31a3e9e9fcf81410029e993b0a9afc" %}
[Match API](/docs/api-reference/match-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/d9d593aeabc52a165190bf8c93720491a4eb9682" %}
[Broken mention](broken://pages/d9d593aeabc52a165190bf8c93720491a4eb9682)
{% endcontent-ref %}

This walkthrough goes deeper than the [Quickstart](broken://pages/d8dde992c3b506ec2b54b125e6aef8f498f18ed3). By the end, you'll have a real project with environment variables, a custom build, and a preview deployment workflow.

{% hint style="info" %}
We'll use a generic web project for this tutorial. The same pattern works for static sites, APIs, and worker services.
{% endhint %}

## 1. Plan your project structure

Before clicking anything, decide how you want to organise your work:

| You have…                  | Use…                                       |
| -------------------------- | ------------------------------------------ |
| One app, one team          | A single project in your default workspace |
| Several related apps       | A workspace with one project per app       |
| Multiple unrelated clients | A separate workspace per client            |

Most people start with the middle option. You can always restructure later.

## 2. Create the project

{% stepper %}
{% step %}

#### From the workspace dashboard

Click **New project**. You'll see three creation options.

{% tabs %}
{% tab title="From a repo" %}
Connect your version control provider and select a repository. The platform detects your framework and pre-fills sensible defaults.
{% endtab %}

{% tab title="From a template" %}
Pick a starting template — blog, dashboard, API, etc. — and the platform creates a new repository for you.
{% endtab %}

{% tab title="Empty project" %}
Skip both and create an empty project. Useful when you want to wire up a custom CLI workflow.
{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Name and configure

Give your project a name and choose its visibility.

* **Public** — anyone with the URL can view the deployed site
* **Private** — only invited members can access it
* **Password-protected** — anyone with the URL and password can view it
  {% endstep %}

{% step %}

#### Set environment variables

If your project needs API keys, database URLs, or other secrets, add them under **Project settings → Environment**.

```bash
DATABASE_URL=postgres://...
API_TOKEN=...
```

{% hint style="warning" %}
Never commit secrets to your repository. Use environment variables for anything sensitive.
{% endhint %}
{% endstep %}
{% endstepper %}

## 3. Customise your build

The platform auto-detects most frameworks, but you can override the defaults in your project's `platform.yaml`:

```yaml
build:
  command: npm run build
  output: dist/
  node: 20
  install: npm ci

deploy:
  framework: auto
  routes:
    - source: /api/*
      destination: /api/[...path].js
```

Common overrides:

* **`build.command`** — the script that produces your output
* **`build.output`** — the folder containing your built files
* **`build.node`** — the Node.js version to use
* **`deploy.routes`** — custom routing rules

## 4. Set up preview deploys

Preview deploys give every branch and pull request its own live URL. They're enabled by default, but you can fine-tune the behaviour:

```yaml
preview:
  enabled: true
  branches:
    include: ["**"]
    exclude: ["release/*"]
  comments: true
```

When `comments: true`, the platform posts a comment on each pull request with the preview URL.

## 5. Deploy

Push to your main branch (or click **Deploy** manually). The platform will:

1. Clone your repository
2. Install dependencies
3. Run your build command
4. Upload the output
5. Promote to your live URL

{% hint style="success" %}
You'll get a notification when the build completes — by email, Slack, or whatever you configured under [Broken mention](broken://pages/d9d593aeabc52a165190bf8c93720491a4eb9682).
{% endhint %}

## Sample project

If you'd like to skip ahead and see a fully configured project, download our sample:

{% embed url="<https://github.com/GitbookIO/gitbook-templates>" %}

## Where to go next

Now that you have a working project, you can check out:

{% content-ref url="/pages/56a52747d54863f8df67ff3ce908938888c69b66" %}
[Broken mention](broken://pages/56a52747d54863f8df67ff3ce908938888c69b66)
{% endcontent-ref %}

{% content-ref url="/pages/d9d593aeabc52a165190bf8c93720491a4eb9682" %}
[Broken mention](broken://pages/d9d593aeabc52a165190bf8c93720491a4eb9682)
{% endcontent-ref %}

{% content-ref url="/pages/fb922e107b31a3e9e9fcf81410029e993b0a9afc" %}
[Match API](/docs/api-reference/match-api.md)
{% endcontent-ref %}

\----------------

A few key concepts shape how everything on the platform fits together. You don't need to memorise these — but skimming them now will save you confusion later.

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><h4><i class="fa-sitemap" style="color:$primary;">:sitemap:</i></h4></td><td><strong>Workspaces &#x26; projects</strong></td><td>The two main containers — and how they relate to each other.</td><td></td></tr><tr><td><h4><i class="fa-lock" style="color:$primary;">:lock:</i></h4></td><td><strong>Permissions</strong></td><td>Who can do what, and how access flows from workspace to project.</td><td></td></tr></tbody></table>

***

### The mental model in 30 seconds

You sign up and get an **account**. Your account belongs to one or more **workspaces**. Each workspace contains **projects**. Members are invited to a workspace and given a role; that role determines what they can do across all projects in that workspace.

That's it — the rest is detail.

## The hierarchy

A workspace contains projects. Projects contain deploys, environment variables, and members.

```mermaid
graph TD
  A[Account] --> W1[Workspace: Acme]
  A --> W2[Workspace: Personal]
  W1 --> P1[Project: Marketing site]
  W1 --> P2[Project: Customer portal]
  W1 --> P3[Project: Internal API]
  P1 --> D1[Production deploy]
  P1 --> D2[Preview deploys]
```

## Workspaces

A workspace is the top-level container for a team's work. It owns:

* The list of members and their roles
* The billing relationship and plan
* Workspace-level settings like SSO and audit logs
* All projects created within it

{% tabs %}
{% tab title="Personal" %}
Free, single-member workspaces. Good for evaluating the platform, side projects, or solo work. Limited to 3 active projects.
{% endtab %}

{% tab title="Team" %}
Multi-member workspaces with shared billing and a common plan. Most teams should use this. Includes audit logs and member roles.
{% endtab %}

{% tab title="Enterprise" %}
Team workspaces with extras — SSO, SCIM provisioning, custom data residency, and a dedicated support contact.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
You can belong to multiple workspaces at once. Switch between them using the workspace picker in the top-left of the dashboard.
{% endhint %}

## Projects

A project is a deployable unit. Each project has:

| Component       | What it does                                     |
| --------------- | ------------------------------------------------ |
| **Source**      | The repository or upload that produces the build |
| **Builds**      | The history of build attempts and their outputs  |
| **Deploys**     | Live versions of the project at a URL            |
| **Environment** | Variables and secrets specific to this project   |
| **Domains**     | The custom domains pointing at this project      |

Projects are isolated from each other. Environment variables, secrets, and configurations don't leak across projects in the same workspace.

## When to split into multiple projects

A common question: "should this be one project or two?"

Use **separate projects** when:

* The codebases are different
* They deploy independently
* They have different sets of secrets
* They need different access controls

Use **one project with multiple environments** when:

* It's the same codebase deploying to different URLs
* You want preview deploys per branch
* The differences are configuration, not code

## Related

{% content-ref url="/pages/fb922e107b31a3e9e9fcf81410029e993b0a9afc" %}
[Match API](/docs/api-reference/match-api.md)
{% endcontent-ref %}

{% content-ref url="/pages/65332f63d0b6cedd6ac718136ba8d89ec6cc1a4d" %}
[Broken mention](broken://pages/65332f63d0b6cedd6ac718136ba8d89ec6cc1a4d)
{% endcontent-ref %}

\-----------------------------

Every member of a workspace has a role. The role determines what actions they can perform across the workspace and its projects.

## Roles overview

There are five roles, ordered from least to most privileged:

| Role         | Best for                                                        |
| ------------ | --------------------------------------------------------------- |
| **Guest**    | External stakeholders who only need to see published deploys    |
| **Viewer**   | Internal users who need read-only access to drafts and settings |
| **Editor**   | Builders who actively work on projects                          |
| **Reviewer** | People who comment and approve, but don't push changes          |
| **Admin**    | Workspace owners and team leads                                 |

{% hint style="info" %}
Guests don't count towards your member limit, making them ideal for read-only stakeholders.
{% endhint %}

## Permission matrix

The full breakdown of what each role can do:

| Action                       | Guest | Viewer | Reviewer | Editor | Admin |
| ---------------------------- | :---: | :----: | :------: | :----: | :---: |
| View published deploys       |   ✓   |    ✓   |     ✓    |    ✓   |   ✓   |
| View drafts                  |   —   |    ✓   |     ✓    |    ✓   |   ✓   |
| Comment on deploys           |   —   |    —   |     ✓    |    ✓   |   ✓   |
| Trigger builds               |   —   |    —   |     —    |    ✓   |   ✓   |
| Edit project settings        |   —   |    —   |     —    |    ✓   |   ✓   |
| Manage environment variables |   —   |    —   |     —    |    ✓   |   ✓   |
| Invite members               |   —   |    —   |     —    |    —   |   ✓   |
| Change roles                 |   —   |    —   |     —    |    —   |   ✓   |
| Manage billing               |   —   |    —   |     —    |    —   |   ✓   |
| Delete projects              |   —   |    —   |     —    |    —   |   ✓   |

## How permissions flow

Roles are assigned at the **workspace level** and apply to every project in that workspace. There's no per-project override.

If you need finer-grained access — for example, contractors who should only see one project — create a separate workspace for that work and invite them there.

{% hint style="warning" %}
Per-project roles are a frequently requested feature and are on our [roadmap](https://example.com/roadmap). For now, the workspace boundary is the boundary of access.
{% endhint %}

## Changing someone's role

Workspace admins can change any member's role at any time:

1. Go to **Workspace settings → Members**
2. Find the member and click the role dropdown next to their name
3. Select the new role and confirm

The change takes effect immediately — the member doesn't need to re-authenticate.

## Removing a member

Removing a member revokes their access immediately. Any content they created stays in the workspace.

{% hint style="danger" %}
If you're using SSO, removing a member from your identity provider does **not** automatically remove them from the workspace unless SCIM provisioning is enabled.
{% endhint %}

\---

Welcome to the platform. These docs cover everything from your first project to advanced workflows — pick a starting point below or ask the Assistant to jump straight to what you need.

<button type="button" class="button primary" data-action="ask" data-icon="gitbook-assistant">Ask a question…</button>

<button type="button" class="button secondary" data-action="ask" data-query="How do I deploy my first project" data-icon="rocket-launch">Deploy your first project</button><button type="button" class="button secondary" data-action="ask" data-query="How do I set up a custom domain" data-icon="globe">Set up a custom domain</button><button type="button" class="button secondary" data-action="ask" data-query="How do I invite my team" data-icon="user-group">Invite your team</button>

***

{% hint style="success" icon="sparkles" %}
**New: scheduled deploys and team-level audit logs.** Schedule deploys for any future date and review every action taken in your workspace.

<a href="https://gitbook.com/docs/changelog" class="button secondary">See what's new</a>
{% endhint %}