deploy

Documentation

Overview

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.

Index

• func CloudflarePages(outputDir, projectName, version string, h *effects.Handle) error
• func Dispatch(cfg Config, outputDir, version, target string, h *effects.Handle) error
• func GitHubPages(outputDir, version, target string, h *effects.Handle) error
• func ResolveCloudflareEnv()
• type Config
• type Error
  • func (e *Error) Error() string
• type UnknownProviderError
  • func (e *UnknownProviderError) Error() string

Functions

func 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.

func 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.

func 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.

func 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.

Types

type Config

type Config struct {
	// Provider selects the implementation: "cloudflare-pages" or
	// "github-pages".
	Provider string
	// Project is the Cloudflare Pages project name. It is read only by the
	// cloudflare-pages provider.
	Project string
}

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

type Error

type Error struct {
	// Message is the diagnostic, rendered verbatim by Error.
	Message string
}

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.

func (*Error) Error

func (e *Error) Error() string

Error returns the diagnostic.

type UnknownProviderError

type UnknownProviderError struct {
	// Provider is the unrecognized provider name, as configured.
	Provider string
}

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.

func (*UnknownProviderError) Error

func (e *UnknownProviderError) Error() string

Error names the unrecognized provider.