45559c0e-d9d4-4741-94b7-ca25b55059d3

Quickstart: Deploy with GitHub

From GitHub repo to a live, SSL-enabled URL using the Forgeon dashboard.

Goal: Connect your GitHub repo, ship a build, and get a live URL — all from the dashboard.

Last updated: 2025-10-20

1) Sign in with GitHub

  • Go to the Forgeon dashboard and click Sign in with GitHub.
  • Approve the requested scopes. We only ask for what’s needed to read repos and set up webhooks.

Using an org? Make sure you have permission to install apps on that org, or ask an owner to approve.

2) Install the Forgeon GitHub App

  • After login, choose Install on GitHub.
  • Select Only select repositories (recommended) and pick your repo, or All repositories if that’s your policy.
  • Confirm installation. You’ll land back in Forgeon.

We use the GitHub App to read commits, receive webhooks, and fetch source for builds.

3) Create a project from your repo

  • In Projects → New Project → Import from GitHub, pick your repository.
  • Name the project (we’ll suggest one).
  • Choose an Environment (e.g., Production) and leave defaults if unsure.

4) Auto-detect & configure

Forgeon inspects your repo and proposes defaults:

  • Framework (e.g., Next.js, Node, Go, Python, Docker)
  • Build command and Output (or Dockerfile)
  • Runtime port and health endpoint (you can adjust later)

Review → Save & Continue.

Tip: If your app listens on a port, bind to 0.0.0.0 and read the PORT env. This keeps deployments portable.

5) First deploy

  • Click Deploy from the project page.
  • We fetch source → build → package artifacts → boot a runtime → attach a preview domain with SSL.

You’ll see live build logs; failures include clear error output and links to fix.

6) See it live

When the status shows Ready, click the Preview URL (e.g., https://auto-xxxx.forgeon.io/).
Share it with teammates — it’s public and TLS-secured.

7) Environment variables (optional)

  • Go to Settings → Environment Variables.
  • Add keys like DATABASE_URL, JWT_SECRET, NODE_ENV, etc.
  • Click Save, then Redeploy to apply.

Secrets are encrypted at rest and only exposed at build/runtime for this project.

8) Custom domain (optional)

  • Open Domains tab → Add Domain (e.g., www.example.com).
  • We’ll show the required DNS records; add them at your registrar.
  • SSL is provisioned automatically once DNS resolves.

9) Rollback (safety net)

  • In Deployments, open the last good build and click Rollback.
  • Traffic returns to the previous healthy version instantly.

10) Invite your team (optional)

  • Settings → Members → Invite to add collaborators with proper roles.

Troubleshooting

  • App builds but page is blank
    Verify the start command and that your server binds to 0.0.0.0 on PORT. Check Runtime Logs for errors.
  • Custom domain pending
    Recheck DNS targets and TTL; propagation can vary. The Domains tab will show current status.
  • Missed webhook
    In GitHub → Settings → Apps → Installed GitHub Apps → Forgeon, confirm the repo is selected and webhooks aren’t blocked by org policy.

What’s next?

  • Deployments — rollbacks, logs, artifacts, previews → Deployments
  • Domains & SSL — custom domains, redirects, certs → Domains & SSL
  • Configuration — ports, health checks, scaling, timeouts → Configuration

Pro tip: Add a lightweight /readyz route and set it as your health check for faster, smarter readiness.