Getting started

This guide walks through the complete first-deployment workflow.

You will:

1. Import a GitHub repository.
2. Review the detected project configuration.
3. Create the first deployment.
4. Open the application and inspect a request.
5. Create a Preview deployment from a branch.
6. Release the change to Production.

Before you begin

You need:

• An Easel account (book a call if you are not on the platform yet)
• A GitHub repository
• Permission to install or authorize the Easel GitHub App
• A supported framework
• Any environment variables required by the application

If you do not have an application ready, start from a small framework starter or an Easel fixture under github.com/easel-sh/easel-sh/tree/main/fixtures.

1. Import a repository

1. Sign in at app.easel.sh.
2. Create or select a workspace.
3. Choose Create Project.
4. Under Import Git Repository, continue with GitHub and authorize the GitHub App if prompted.
5. Select the repository and continue to New Project.

Easel reads the repository and attempts to detect:

• Framework
• Project root
• Install command
• Build command
• Output directory
• Production branch (default main)

The GitHub App requests permissions needed for repository contents, commit statuses, deployments, pull-request discovery, and PR preview comments. See Git deployments.

2. Review project configuration

Before deploying, confirm the detected settings on the New Project screen.

Framework

Make sure Easel selected the correct framework. The framework controls build behavior, route discovery, function bundling, static output, and related defaults.

See the matching framework guide.

Root directory

For a monorepo, select the directory containing the application.

Example:

apps/web

Build settings

Review:

Install command
Build command
Output directory

Use the framework defaults unless the repository requires custom settings.

Production branch

Choose the branch that should create Production deployments. A common choice is main. Pushes to other branches create Preview deployments.

You can change this later in Project settings → Environments.

Environment variables

Add variables required by the build or application before deploying.

Use different values for Preview and Production when the application should connect to separate services. Configure them in Project settings → Environment Variables.

See Deployment environments.

3. Create the first deployment

Choose Deploy.

Easel creates a deployment and moves it through statuses such as Queued, Building, and Ready. Open the build logs while the deployment runs.

If the build fails, start with the first actionable error rather than the final process-exit message. See Deployment troubleshooting.

First-deployment behavior

Connecting a repository triggers an initial build. The environment follows the usual mapping:

• The configured Production branch creates a Production deployment
• Other branches create Preview deployments

Auto-assign production domains is on by default. When a Production deployment reaches Ready, Easel marks it Current and assigns the project Production URL and live custom domains. If auto-assign is off, the deployment stays Staged until you promote it.

The default project URL looks like:

https://{project}-{workspace}.preview.easelusercontent.com

See Deployment URLs.

4. Open the deployment

When the deployment reaches Ready, open its deployment URL.

Confirm:

• The homepage loads
• A deep route loads
• Static assets load
• Server-rendered or API routes work
• Authentication initializes correctly, when applicable

A unique deployment URL identifies that specific commit deployment. Stable branch Preview and Production URLs may point to different deployments over time.

5. Inspect a request

Generate a request by opening the deployed application.

Then:

1. Open the project in Easel.
2. Select Logs (or Observability for charts).
3. Find the request you just generated.
4. Open the request detail, then the Logs and Trace tabs.

See Request details and Observability.

6. Create a Preview deployment

Create a branch locally:

git checkout -b improve-homepage

Make a visible change, commit it, and push the branch:

git add .
git commit -m "Improve homepage"
git push -u origin improve-homepage

Easel creates a new Preview deployment that:

• Uses Preview configuration
• Does not replace Production traffic
• Receives a unique deployment URL
• Updates a stable branch Preview URL after it reaches Ready
• Can attach a pull-request Preview URL when a PR is open

Open the Preview URL and verify the change. See Preview deployments.

7. Open a pull request

Open a pull request from the feature branch into the Production branch.

The GitHub integration can show deployment status, Preview URL, and commit checks on the pull request. Each new commit creates another deployment. The stable Preview URL moves only after the new deployment reaches Ready.

8. Release to Production

Production-branch workflow (default)

When auto-assign is on:

1. Merge the pull request.
2. The merge commit on the Production branch creates a new Production deployment (Preview artifacts are not reused for production traffic).
3. The current Production deployment continues serving traffic while the new deployment builds.
4. After the new deployment reaches Ready, Easel assigns Production traffic to it.

A failed deployment leaves the previous Current deployment in place.

Manual release workflow

When Auto-assign production domains is off:

1. Create or wait for a Ready Production deployment (Staged).
2. Review it on its unique URL.
3. Choose Promote to make it Current.

Promoting a Preview deployment rebuilds with Production environment variables. Instant promote of a Staged Production deployment does not rebuild.

See Promoting deployments.

9. Verify Production

Open the Production URL and confirm:

• The new change is present
• The expected deployment is marked Current
• Requests appear in Logs
• Functions and APIs work
• Cache behavior is expected
• No new runtime errors appear

Platform protections

Every supported deployment receives Easel’s platform protections automatically. You do not need custom firewall rules before making a normal application available.

For project-specific controls, see:

• Firewall
• Custom rules
• Attack Mode

Add a custom domain

After verifying Production, connect a domain you control.

See Add a custom domain.

What you have now

You now have:

• A GitHub-connected Easel project
• A Ready deployment
• A defined Production branch
• Automatic Preview deployments
• A Production release workflow
• Request-level observability
• Easel platform protections

For AI agents

Prefer Markdown over HTML when reading these docs:

• Append .md to any docs URL (for example /docs/getting-started.md), or send Accept: text/markdown.
• Index: /llms.txt · Full corpus: /llms-full.txt
• MCP server for Cursor and other clients: /api/mcp

Next steps