Repository

Source: src/GitHub/Repository.ts

A GitHub repository.

Repository manages the lifecycle of a repository owned by a user or organization. The repository is created on first deploy and its settings are converged on every subsequent deploy.

Repositories default to retain on removal — destroying the stack does NOT delete the repository on GitHub, protecting its irreplaceable history (issues, pull requests, commits). Opt in to actual deletion by wrapping the resource (or the whole stack) in {@link destroy}() from alchemy/RemovalPolicy.

Authentication is resolved via the GitHubCredentials service supplied by GitHub.providers() (env, stored PAT, gh CLI, or OAuth). The token needs repo scope (and delete_repo when deletion is opted in via destroy()).

Creating a Repository

Basic Repository

const repo = yield* GitHub.Repository("api", {
  owner: "my-org",
  name: "api",
  description: "API service",
  autoInit: true,
});

Private Repository with Settings

const repo = yield* GitHub.Repository("internal-tools", {
  owner: "my-org",
  name: "internal-tools",
  visibility: "private",
  hasWiki: false,
  hasProjects: false,
  deleteBranchOnMerge: true,
});

Initialize from Templates

The autoInit, gitignoreTemplate, and licenseTemplate props seed the first commit. They are only honored at create time — changing them on a later deploy has no effect on an existing repository.

const repo = yield* GitHub.Repository("service", {
  owner: "my-org",
  name: "service",
  autoInit: true,
  gitignoreTemplate: "Node",
  licenseTemplate: "mit",
});

Topics and Merge Configuration

const repo = yield* GitHub.Repository("sdk", {
  owner: "my-org",
  name: "sdk",
  topics: ["typescript", "effect", "sdk"],
  allowMergeCommit: false,
  allowRebaseMerge: false,
  allowSquashMerge: true,
  allowAutoMerge: true,
});

Renaming a Repository

Keep the same logical ID and change name to rename the live repository instead of replacing it — the repository’s history, issues, and pull requests are preserved. Only changing owner triggers a replacement.

// First deploy creates "api".
const repo = yield* GitHub.Repository("api", {
  owner: "my-org",
  name: "api",
});

// A later deploy with the SAME logical ID ("api") renames it to "gateway".
const repo = yield* GitHub.Repository("api", {
  owner: "my-org",
  name: "gateway",
});

Archiving a Repository

Archiving sets the repository to read-only. Set archived back to false on a later deploy to un-archive it.

yield* GitHub.Repository("legacy", {
  owner: "my-org",
  name: "legacy-service",
  archived: true,
});

Wiring with Other Resources

The repository’s outputs can drive other GitHub resources so the whole repository configuration lives in one program.

Seed a Variable into the Repository

const repo = yield* GitHub.Repository("api", {
  owner: "my-org",
  name: "api",
  autoInit: true,
});

yield* GitHub.Variable("region", {
  owner: "my-org",
  repository: repo.name!,
  name: "AWS_REGION",
  value: "us-east-1",
});

Store a Secret in the Repository

import * as Redacted from "effect/Redacted";

const repo = yield* GitHub.Repository("api", {
  owner: "my-org",
  name: "api",
  autoInit: true,
});

yield* GitHub.Secret("deploy-token", {
  owner: "my-org",
  repository: repo.name!,
  name: "DEPLOY_TOKEN",
  value: Redacted.make("my-secret-value"),
});

Deleting a Repository

import { destroy } from "alchemy/RemovalPolicy";

yield* GitHub.Repository("ephemeral", {
  owner: "my-org",
  name: "ephemeral-preview",
}).pipe(destroy());