WikiPage

Source: src/GitHub/WikiPage.ts

A GitHub wiki page.

WikiPage manages the lifecycle of a page in a repository’s wiki. Wiki pages are created on first deploy and updated in place on subsequent deploys when the content changes. By default, pages are never deleted to preserve documentation history — set allowDelete: true to opt in.

The repository’s wiki must be enabled (hasWiki: true on the Repository resource) and initialized by creating its first page in the GitHub web UI. Enabling the wiki or setting autoInit on the repository does not initialize the separate wiki Git repository. An inaccessible or uninitialized wiki produces WikiRepositoryUnavailable with setup instructions.

Git must be installed on the deployment machine. Pages are managed through the wiki’s Git repository, not the GitHub REST API. Each content or format change creates a commit; unchanged pages do not. Concurrent pushes are retried against a fresh checkout without force-pushing. Deletion removes the current page file, not its Git history. Authentication uses a transient process-environment header; tokens are not stored in clone URLs or Git config.

Authentication is resolved via the GitHubCredentials service supplied by GitHub.providers() (env, stored PAT, gh CLI, or OAuth). The token needs repo scope for private repositories or public_repo for public ones.

Creating Wiki Pages

Basic Wiki Page

const home = yield* GitHub.WikiPage("home", {
  owner: "my-org",
  repository: "my-repo",
  title: "Home",
  content: "Welcome to the wiki!",
});

Formatted Wiki Page

yield* GitHub.WikiPage("getting-started", {
  owner: "my-org",
  repository: "my-repo",
  title: "Getting Started",
  content: `
    # Getting Started

    Install the package:

    \`\`\`bash
    npm install my-package
    \`\`\`
  `,
  format: "markdown",
  message: "Add getting started guide",
});

Updating Wiki Pages

Deploy with the same logical ID and a different content to update the existing page in place rather than creating a new one.

yield* GitHub.WikiPage("api-docs", {
  owner: "my-org",
  repository: "my-repo",
  title: "API Documentation",
  content: "Updated API documentation content",
});

Alternative Formats

yield* GitHub.WikiPage("architecture", {
  owner: "my-org",
  repository: "my-repo",
  title: "Architecture",
  content: `
    = System Architecture

    == Overview

    The system is built with...
  `,
  format: "asciidoc",
});

Deleting Wiki Pages

const temp = yield* GitHub.WikiPage("temp-page", {
  owner: "my-org",
  repository: "my-repo",
  title: "Temporary Page",
  content: "This page can be deleted",
  allowDelete: true,
});

Wiring with Other Resources

Deploy the repository first and create its first wiki page in the GitHub web UI before adding WikiPage to the stack.

import * as Output from "alchemy/Output";

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

yield* GitHub.WikiPage("home", {
  owner: repo.owner!,
  repository: Output.map(repo.fullName, (fullName) => fullName.split("/")[1]!),
  title: "Home",
  content: "Welcome to the documentation wiki!",
});