Skip to content
internal/deploy
Updated
On this page

Publishing a built documentation site through one of two providers: Cloudflare Pages via the wrangler CLI, or GitHub Pages by force-pushing a branch.

#internal/deploy

#internal/deploy

Package deploy publishes a built documentation site.

Two providers are supported, selected by the "provider" key of the deploy section of selfdoc.json and dispatched by [Dispatch]:

- Cloudflare Pages, through the wrangler CLI; - GitHub Pages, by force-pushing the built tree to a gh-pages branch.

#Error

Go go
type Error struct

Error is the failure every deploy operation reports: a missing wrangler, an unusable push target, a git step that failed, a deploy that timed out, and a provider command that exited non-zero.

It is the Go counterpart of the Python surface's DeployError, and the one error type a caller needs to recognize with errors.As to render "Deploy error" diagnostics distinctly from an unexpected internal failure.

#UnknownProviderError

Go go
type UnknownProviderError struct

UnknownProviderError is returned by [Dispatch] for a deploy section naming a provider this package does not implement. It is a distinct type rather than an [Error] because it reports a malformed configuration rather than a deploy that went wrong, and the CLI renders the two differently.

#Config

Go go
type Config struct

Config is the decoded "deploy" section of selfdoc.json.

#Dispatch

Go go
func Dispatch(cfg Config, outputDir, version, target string, h *effects.Handle) error

Dispatch deploys outputDir through the provider cfg names.

version is the version string the deploy's commit message carries. target is the GitHub Pages push target and is ignored by the Cloudflare provider; see [GitHubPages] for what a target may be and why it is never inferred.

A provider this package does not implement is an [UnknownProviderError].

#CloudflarePages

Go go
func CloudflarePages(outputDir, projectName, version string, h *effects.Handle) error

CloudflarePages deploys outputDir to the Cloudflare Pages project projectName using the wrangler CLI, with version in the deploy's commit message.

wrangler must be installed and authenticated, either through wrangler login or through the credential variables [ResolveCloudflareEnv] bridges.

Under a handle in preview mode the upload is recorded rather than performed, and nothing is reported as deployed.

#ResolveCloudflareEnv

Go go
func ResolveCloudflareEnv()

ResolveCloudflareEnv bridges the CF_-prefixed credential variables to the CLOUDFLARE_-prefixed ones wrangler reads.

The canonical names here are CF_ACCOUNT_ID and CF_PAGES_API_TOKEN; wrangler expects CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN. An already-set CLOUDFLARE_ variable is never overwritten.

It sets them on this process's own environment, which is what the child inherits: passing them as an explicit child environment instead would mean handing the effects handle the whole inherited environment as overrides, and a preview would then render every variable this process holds.

#GitHubPages

Go go
func GitHubPages(outputDir, version, target string, h *effects.Handle) error

GitHubPages deploys outputDir by force-pushing it to the remote's gh-pages branch, with version in the commit message.

The tree is staged in a temporary directory, so the current working tree is never touched, and a .nojekyll file is written so GitHub serves the built HTML instead of running Jekyll over it.

target is the required push target: either a git remote URL, used verbatim, or the path of a repository whose "origin" remote is resolved. It is deliberately not derived from the process's working directory -- this function FORCE-pushes a gh-pages branch, and a target taken from the working directory silently aims that force-push at whatever repository the process happens to be sitting in.

Under a handle in preview mode every step is recorded rather than performed, and nothing is reported as deployed.

#Error.Error

Go go
func (e *Error) Error() string { return e.Message }

Error returns the diagnostic.

#UnknownProviderError.Error

Go go
func (e *UnknownProviderError) Error() string

Error names the unrecognized provider.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search