#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

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

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

type Config struct

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

#Dispatch

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

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

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

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

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

Error returns the diagnostic.

#UnknownProviderError.Error

func (e *UnknownProviderError) Error() string

Error names the unrecognized provider.