Git Integration

Overview

Connect a GitHub repository to a Hostess project and Hostess deploys it for you — no CI pipeline required:

• Deploy on push — a push to a tracked branch builds and deploys to the matching environment.
• Pull request previews — every PR gets its own isolated preview deployment with a unique URL, posted back as a comment.
• Commit statuses — each deploy reports pending → success/failure on the commit.

This is the zero-config path. If you'd rather drive deploys from your own pipeline (or a non-GitHub source), use a Personal Access Token with CI/CD instead — the two can coexist.

Connect a repository

There are three ways to link a repo to a project. All of them result in the same connection.

From Studio (recommended)

1. Open your project → Settings → Git.
2. If you haven't installed the Hostess GitHub App yet, click Install GitHub App and grant access to the repositories you want to deploy.
3. Back in Settings → Git, pick the repository from the list and click Connect.

You can also start from scratch on the Projects page with Import from GitHub, which creates the project and connects the repo in one step.

From the CLI

Run hostess deploy inside a repo that has no repo: block in its hostess.yml. Hostess detects your origin remote and offers to link it:

Detected remote repo my-org/my-app. Link to this project? [y/N]

Accepting writes a repo: block to your hostess.yml and connects the project on the next deploy.

In hostess.yml

Declare the repository directly:

repo:
  provider: github
  owner: my-org
  name: my-app

Branch → environment routing

When a push or PR arrives, Hostess matches the branch against each environment's branch patterns and deploys to the first match. Configure patterns per environment in hostess.yml:

environments:
  production:
    branches: [main]          # exact branch → production
  staging:
    branches: ["release/*"]   # glob → staging
  preview:
    branches: ["*"]           # catch-all for everything else
    ephemeral: true
    ttl: 24h

Matching rules:

• An exact branch name beats a glob; a more specific glob beats *.
• If nothing matches, the branch falls back to the ephemeral (preview) environment.
• Branch deletes and tag pushes are ignored.

A new project starts with a production environment and an ephemeral preview environment, so previews work out of the box.

Deploy on push

Push to a tracked branch and Hostess:

1. Fetches your source at that commit.
2. Resolves the target environment from the branch.
3. Builds and deploys, reporting a hostess/deploy commit status (pending → success/failure).

A push to main (or whatever your production environment tracks) deploys production; pushes to other branches deploy to the resolved environment (preview by default).

Pull request previews

Open a pull request and Hostess deploys an isolated preview for it:

• Each PR runs in its own isolated environment and gets autogenerated URLs: https://{project}-{service}-pr-{number}.hostess.run
• The preview URLs are posted as a comment on the PR (and refreshed on each push).
• The commit status links back to the deployment in Studio.
• When the PR is closed or merged, the preview is torn down automatically. Abandoned previews are also reaped once they pass the preview environment's ttl.

Custom domains per environment

Custom domains attach to an environment's stable deployment and are additive to the autogenerated URLs:

environments:
  production:
    domains:
      app: [myapp.com, www.myapp.com]

See Custom Domains for DNS setup. In Studio, a service shows all of its URLs in priority order: custom domain → preview → stable → deployment.

What gets deployed

Hostess reads hostess.yml from the repository at the pushed commit and deploys exactly what it declares — the same config you use locally. Build-from-source, file mounts, and env_file all resolve from the repository tree, so a webhook deploy behaves identically to hostess deploy from your laptop.