# Forge

Call GitHub as your GitHub App, or GitLab and Forgejo with a token. You write no JWT or token code.

```sh [.env]
# Local development: the private PEM file must exist at runtime
VITEHUB_GITHUB_APP_ID=123456
VITEHUB_GITHUB_PRIVATE_KEY_PATH=./github-app.pem
```

```ts [server/api/issues.post.ts]
import { defineEventHandler, HTTPError } from 'h3'
import { useForge } from 'vite-hub/forge'

// Sends the installation token of acme/web
export default defineEventHandler(async () => {
  const [error, github] = await useForge().provider({ repository: 'acme/web' })
  if (error) throw new HTTPError({ status: 502, message: error.why })

  const { data } = await github.request<{ html_url: string }>('POST', '/repos/acme/web/issues', {
    body: { title: 'Nightly build failed' },
  })
  return { url: data.html_url }
})
```

```ts [server/utils/github-env.ts]
import { useForge } from 'vite-hub/forge'

// Give the token to git or gh
export async function githubEnv(repository: string) {
  const [error, token] = await useForge().token({ repository })
  if (error) return error
  return { GH_TOKEN: token.token }
}
```

For production, [provide credentials for your host](https://vitehub.dev/docs/forge/get-started#in-production).

### [Act as your GitHub App](https://vitehub.dev/docs/forge/get-started)

`useForge()` signs the App JWT, finds the installation, and mints installation tokens.

### [A typed Forge client](https://vitehub.dev/docs/forge/server-api#call-the-api-as-the-app)

`provider()` returns a `forges` client. A GitHub client also has `graphql()`.

### [GitHub, GitLab, and Forgejo](https://vitehub.dev/docs/forge/server-api#use-gitlab-or-forgejo)

Pass `forge`, and the client type follows it.

### [One set of env names](https://vitehub.dev/docs/forge/configure)

Routes, the GitHub Channel, and Agents read the same `VITEHUB_GITHUB_*` names.

### [Repository tools for Agents](https://vitehub.dev/docs/agents/capabilities/forge)

The `forge()` Capability and the GitLab and Forgejo Channels use the same Forge.

### [Errors without try/catch](https://vitehub.dev/docs/forge/limits-and-errors)

Each call returns `[error, data]`. A configuration that cannot work throws at the first call.

Use Forge when server code calls GitHub, GitLab, or Forgejo as the app. Install `@vite-hub/forge` and import `useForge()` from `vite-hub/forge`. Do not write JWT or installation token code, and do not read `GH_TOKEN` or `GITHUB_TOKEN`.

Get a new provider for each job. Pass `repository` so a GitHub App finds the right installation. Import Forge error classes, such as `NotFoundError`, from `@vite-hub/forge`, not from `forges`.

Prove it with a real App or token against a test repository. Without credentials, show that `useForge()` throws `FORGE_MISSING_ENV` with the variables to set.

<!-- vitehub-docs:section-links -->
## In this section

- [Overview](https://vitehub.dev/raw/docs/forge.md) (this page)
- [Get started](https://vitehub.dev/raw/docs/forge/get-started.md)
- [Configure](https://vitehub.dev/raw/docs/forge/configure.md)
- [Server API](https://vitehub.dev/raw/docs/forge/server-api.md)
- [Limits and errors](https://vitehub.dev/raw/docs/forge/limits-and-errors.md)

Next: [FORGE_APP_NOT_INSTALLED](https://vitehub.dev/raw/docs/forge/diagnostics/forge_app_not_installed.md)

All pages: [llms.txt](https://vitehub.dev/llms.txt)
