# Publish with Forge

1. Choose a project name or have Forge generate one with POST /api/projects (JSON body with an optional name). Open the returned approval_url in the user's browser. POST id and poll_secret to token_url until it returns the project token and HTTPS remote. A 202 response means approval is pending.
2. Initialize Git if needed, commit a working branch, and add the returned remote under the name forge. Keep the token out of the remote URL. For Git operations, set GIT_CONFIG_COUNT=1, GIT_CONFIG_KEY_0=http.extraHeader and GIT_CONFIG_VALUE_0 to "Authorization: Bearer <token>" in the command environment. Push the working branch. Direct updates to main are rejected.
3. GET /api/projects/<name>/releases?branch=<branch>&commit=<sha> using the same Bearer credential. Poll until ready or failed. Read the error and push a new commit if needed.
4. On the user's request to publish, POST {"branch":"<branch>","commit":"<sha>"} to /api/projects/<name>/merges. Poll the release endpoint until live. Report the returned URLs. To revoke the current credential, DELETE /api/projects/<name>/credential.

## Projects and checks

Static HTML needs an index.html. For Vite and Next.js, commit a package-lock.json; Forge uses npm ci. Next.js apps can use the standalone output convention. An explicit Dockerfile takes precedence. Expose your HTTP service on all interfaces using PORT and provide GET /healthz (or declare a health path). Put each service in its own directory. Declare npm scripts for applicable checks, or run language-specific checks in your Dockerfile.

A multi-service project can use:

```yaml
services:
  - name: web
    path: ./web
    primary: true
  - name: api
    path: ./api
    health: /healthz
database: postgres
```

Use renamed_from on a renamed service to preserve its identity and hostname. Store compatible SQL migrations under migrations/NNNN-name.sql in the project root. A provisioned database is exposed to runtime code as DATABASE_URL. Branch tests get disposable database data. Changes to production data require a successful merge and main checks.

To set or rotate an app secret, POST /api/projects/<name>/secrets using the bearer credential and give the returned one-use URL to the owner. The next deployment picks up the new value. To restore the preceding release, POST /api/projects/<name>/rollback. Check readiness and the returned service URLs. Preview URLs are deferred.
