Your first project

A guided walkthrough that takes you from an empty workspace to a configured, deployed project.

This walkthrough goes deeper than the Quickstart. By the end, you'll have a real project with environment variables, a custom build, and a preview deployment workflow.

We'll use a generic web project for this tutorial. The same pattern works for static sites, APIs, and worker services.

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

1

From the workspace dashboard

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

From a repo

Connect your version control provider and select a repository. The platform detects your framework and pre-fills sensible defaults.

From a template

Pick a starting template — blog, dashboard, API, etc. — and the platform creates a new repository for you.

Empty project

Skip both and create an empty project. Useful when you want to wire up a custom CLI workflow.

2

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

3

Set environment variables

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

DATABASE_URL=postgres://...
API_TOKEN=...

Never commit secrets to your repository. Use environment variables for anything sensitive.

3. Customise your build

The platform auto-detects most frameworks, but you can override the defaults in your project's platform.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:

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

You'll get a notification when the build completes — by email, Slack, or whatever you configured under Automations.

Sample project

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

GitHub - GitbookIO/gitbook-templates: A collection of templates available in GitBook.GitHub

Where to go next

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

Custom domainsAutomationsPermissions