45559c0e-d9d4-4741-94b7-ca25b55059d3
Forgeon Docs

Documentation, guides, and patterns to help you build on Forgeon — from your first deploy to running serious infrastructure.

Sign in with GitHub

Log in to Forgeon and connect your GitHub repositories via the Forgeon GitHub App.

# Click “Sign in with GitHub”

1) Log in

  • Go to the Forgeon Dashboard and choose Sign in with GitHub.
  • Approve the OAuth prompt to let Forgeon identify you and read basic profile info.

Using a GitHub organization? You may need an Owner (or someone with app install rights) to approve the app for that org.

2) Install the Forgeon GitHub App

  • After login, click Install on GitHub.
  • Choose where to install:
    • Your personal account, or
    • A GitHub organization you belong to.
  • Scope selection:
    • Only select repositories (recommended) → pick a repo,
    • or All repositories if your policy prefers it.
  • Confirm installation. You’ll be returned to Forgeon.

Least-privilege is best: pick “Only select repositories” and add repos as you go.

3) Create a project from a repo

  • In Projects → New Project → Import from GitHub, pick the repository you installed.
  • Name the project (we’ll suggest one).
  • Choose an Environment (start with Production; you can add Staging later).

4) Auto-detect & review

Forgeon inspects your repo and proposes sensible defaults:

  • Framework: Next.js, Nuxt, SvelteKit, Remix, Astro, Express, Django, Flask, FastAPI, Go, Rails, Spring Boot, .NET, Rust, etc.
  • Build command and Output (or Dockerfile if present)
  • Runtime: port and health check

Review and Save. You can override anytime in Settings → Configuration.

Your app must bind 0.0.0.0 and listen on the PORT environment variable. If it hardcodes localhost or a fixed port, traffic won’t reach it.

5) First deploy

  • Click Deploy on the project page.
  • We fetch source → build → package → boot a runtime → attach a Preview URL with SSL.
  • Watch Build Logs; errors include direct hints to fix.
next steps

Permissions we request (at a glance)

  • Repository contents (read) — fetch code for builds
  • Webhooks (read/write) — trigger deploys on pushes
  • Metadata (read) — repo info for UI
  • Checks/Statuses (optional) — annotate PRs (if enabled later)

We do not request write access to code.

Troubleshooting

  • Can’t see your repo during import
    Ensure the app is installed on the correct account/org and that the repo is selected (GitHub → Settings → Apps → Installed GitHub Apps → Forgeon → Configure).
  • Org blocks third-party apps
    Ask an org Owner to approve the Forgeon app or allow it for your team.
  • Build succeeded but site is blank
    Verify your server binds 0.0.0.0 on PORT. Check Runtime Logs for stack traces.
  • Custom domain pending
    Add the DNS targets shown in Domains and wait for propagation; SSL provisions automatically.

What’s next?