feat(forgejo): Forgejo provider for self-hosted instances

[wyattjoh]

Adds a Forgejo provider for self-hosted Forgejo instances. It talks to Forgejo's REST API directly, no vendor SDK, so it works against any instance reachable with a token.

Quick start

import * as Alchemy from "alchemy";
import * as Forgejo from "alchemy/Forgejo";
import * as Effect from "effect/Effect";
import * as Redacted from "effect/Redacted";

export default Alchemy.Stack(
  "Repos",
  { providers: Forgejo.providers(), state: Alchemy.localState() },
  Effect.gen(function* () {
    const repo = yield* Forgejo.Repository("api", {
      owner: "acme",
      name: "api",
      private: true,
      autoInit: true,
      topics: ["typescript", "effect"],
    });

    yield* Forgejo.Secrets({
      owner: "acme",
      repository: "api",
      secrets: { DEPLOY_TOKEN: Redacted.make(process.env.DEPLOY_TOKEN!) },
    });

    return { url: repo.htmlUrl };
  }),
);

Provider surface

API	Purpose
Repository	Creates, adopts, renames, and converges repository settings and topics
Organization	Organizations, via Forgejo's admin endpoints
Team / TeamMember	Org teams, their permission units, and membership
Label	Repository issue and pull-request labels
BranchProtection	Protected-branch rules, approvals, status checks, push allowlists
Secret / Secrets	Actions secrets, scoped to a repository, organization, or user
Variable / Variables	Actions variables, same three scopes
Webhook	Repository webhooks
ApiToken	Mints a Forgejo access token, exposed as a Redacted output

Repositories and organizations default to the retain removal policy, matching the GitHub provider. Renaming a repository (same logical ID, new name) renames in place; changing owner replaces.

Auth

Forgejo is registered as an auth provider via makeStoredAuthProvider, and added to the built-in registry in Alchemist/Session.ts. Because Forgejo is self-hosted, the instance URL is part of the credential rather than a constant, so the provider collects and stores it next to the token:

alchemy profile edit --add Forgejo --method stored \
  --set baseUrl=https://git.example.com \
  --set token=<access token>

alchemy profile edit --add Forgejo connects an instance interactively. providers() resolves from the selected profile, falling back to FORGEJO_URL / FORGEJO_TOKEN in CI. Passing providers({ baseUrl, token }) pins both in code and bypasses profile resolution.

A stored token is the only method here. Forgejo does support custom OAuth2 applications (public client + PKCE), but its OAuth2 tokens are unscoped and carry full administrative rights, where a personal access token can be limited to write:repository. An oauth method can be added later as a second variant, the way CloudflareAuthConfigSchema unions stored and oauth.

Client

Every API failure is a tagged error rather than an HTTP status check, so lifecycle code branches on Effect.catchTag:

export type ForgejoError =
  | ForgejoNotFound
  | ForgejoUnauthorized
  | ForgejoForbidden
  | ForgejoConflict
  | ForgejoValidationError
  | ForgejoServerError
  | ForgejoRequestError
  | ForgejoTransportError;

The credential layers resolve HttpClient from the environment rather than constructing one, so providers() leaves it in RIn (satisfied by StackServices) and a caller can substitute a different implementation:

Forgejo.providers({ baseUrl, token }).pipe(Layer.provide(myHttpClient))

List endpoints paginate through paginate() rather than taking Forgejo's default 30-entry first page.

Differences from the GitHub provider

• Forgejo accepts Actions secrets as plaintext over authenticated TLS. There is no public-key encryption handshake, so every deploy writes the value.
• Organizations, teams, and ApiToken go through Forgejo's /admin endpoints and need an administrator credential.
• No repository event source, Webhook only.

Docs

New /forgejo hub (overview, setup, repositories, Actions config, organizations & teams), registered in the sidebar, docs tabs, provider directory, and icon map.

[sam-goodwin]

This needs to be deleted ands implemented as a generated SDK in https://github.com/alchemy-run/distilled and patched to include tagged errors. We don't accept providers without this.

[sam-goodwin]

cc @Mkassabov who can help with generating SDKs

[wyattjoh]

Opened a PR over here alchemy-run/distilled#541, will update this one once it's merged and available.