deploy

package
v1.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 18, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Overview

Package deploy publishes a built site to a hosting provider.

Every deployer takes its credentials from environment variables, never from sarde.yaml, and reports progress through a Reporter instead of printing, so the CLI can render human lines or a JSON event stream.

Index

Constants

View Source
const (
	CodeAuth        = "auth"         // token missing scopes, rejected or expired
	CodeNotFound    = "not_found"    // site or project does not exist
	CodeRateLimited = "rate_limited" // provider throttled us past the retry budget
	CodeLimit       = "limit"        // file count or size over a provider limit
	CodeNetwork     = "network"      // could not reach the provider
	CodeCanceled    = "canceled"     // the caller cancelled
	CodeConfig      = "config"       // missing or invalid local configuration
	CodeProvider    = "provider"     // any other provider-side failure
)

Error codes reported by ErrorCode. They reach Sarde Studio through the JSON error envelope, so the values are part of the CLI contract.

View Source
const (
	LevelInfo = "info"
	LevelWarn = "warn"
)

Log levels for Reporter.Log.

Variables

This section is empty.

Functions

func ErrorCode added in v1.5.0

func ErrorCode(err error) string

ErrorCode classifies a deploy error for machine consumers. It returns "" for nil.

Types

type APIError added in v1.5.0

type APIError struct {
	Provider  string
	Endpoint  string // "POST /sites/{id}/deploys", ids elided
	Status    int
	Code      string // provider error code, when the body carries one
	Message   string
	Retryable bool
	// Body is the raw response body, for callers that need structured
	// fields the generic decoder drops (Vercel's missing_files list).
	Body []byte
}

APIError is a non-success response from a provider API.

func (*APIError) Error added in v1.5.0

func (e *APIError) Error() string

type CheckResult added in v1.5.0

type CheckResult struct {
	Provider string `json:"provider"`
	TargetID string `json:"target_id,omitempty"`
	Target   string `json:"target,omitempty"` // site or project name
	URL      string `json:"url,omitempty"`    // the target's production URL
	Account  string `json:"account,omitempty"`
}

CheckResult describes the target a credential check reached.

type Checker added in v1.5.0

type Checker interface {
	Check(ctx context.Context, rep Reporter) (*CheckResult, error)
}

Checker is implemented by deployers that can verify credentials and access to the configured target without uploading anything.

type CloudflareDeployer

type CloudflareDeployer struct {
	ProjectName string
	AccountID   string
	// contains filtered or unexported fields
}

CloudflareDeployer publishes to Cloudflare Pages with direct upload: the same protocol `wrangler pages deploy` uses. Credentials: the CLOUDFLARE_API_TOKEN environment variable (Pages Write permission), the account id (deploy.account_id, or CLOUDFLARE_ACCOUNT_ID, which wins) and deploy.project_name.

The project and deployment endpoints are documented (https://developers.cloudflare.com/api/resources/pages/). The asset upload endpoints are not: they are defined by wrangler's source (packages/wrangler/src/pages/upload.ts), so everything that touches them lives in cloudflare_upload.go and names the endpoint in its errors.

func (*CloudflareDeployer) Check added in v1.5.0

Check looks the project up and fetches an upload token: it proves both read and write access and uploads nothing.

func (*CloudflareDeployer) Deploy

func (d *CloudflareDeployer) Deploy(ctx context.Context, distDir string, rep Reporter) (*Result, error)

func (*CloudflareDeployer) Name

func (d *CloudflareDeployer) Name() string

type CustomDeployer

type CustomDeployer struct {
	Command string
	// contains filtered or unexported fields
}

CustomDeployer runs a user-provided shell command with DIST_DIR set to the absolute output directory.

func (*CustomDeployer) Deploy

func (d *CustomDeployer) Deploy(ctx context.Context, distDir string, rep Reporter) (*Result, error)

func (*CustomDeployer) Name

func (d *CustomDeployer) Name() string

type Deployer

type Deployer interface {
	Name() string
	Deploy(ctx context.Context, distDir string, rep Reporter) (*Result, error)
}

Deployer publishes a built output directory.

func NewDeployer

func NewDeployer(cfg config.DeployConfig, opts Options) (Deployer, error)

NewDeployer creates the Deployer for cfg.Provider.

type File added in v1.5.0

type File struct {
	// Rel is the path relative to the output directory, with forward
	// slashes and no leading slash ("blog/index.html"). It is the only path
	// form that ever reaches a provider manifest.
	Rel  string
	Abs  string
	Size int64
}

File is one file of the built site as a deployer sees it.

type GitHubPagesDeployer

type GitHubPagesDeployer struct {
	Branch string
	// CNAME is the custom domain written to the published CNAME file. Empty
	// keeps whatever CNAME the output already contains (for example one
	// copied from static/).
	CNAME string
	// contains filtered or unexported fields
}

GitHubPagesDeployer deploys to GitHub Pages by force-pushing the output to a branch of the project's origin remote, using the git credentials already configured on the machine.

func (*GitHubPagesDeployer) Check added in v1.5.0

Check verifies the origin remote is reachable with the current git credentials (`git ls-remote`, read-only).

func (*GitHubPagesDeployer) Deploy

func (d *GitHubPagesDeployer) Deploy(ctx context.Context, distDir string, rep Reporter) (*Result, error)

func (*GitHubPagesDeployer) Name

func (d *GitHubPagesDeployer) Name() string

type NetlifyDeployer

type NetlifyDeployer struct {
	SiteID string
	// contains filtered or unexported fields
}

NetlifyDeployer publishes through Netlify's file-digest deploy API: send a manifest of SHA1 digests, upload only the files Netlify does not already have, then wait for the deploy to go live. Credentials: the NETLIFY_AUTH_TOKEN environment variable and deploy.site_id.

API reference: https://docs.netlify.com/api-and-cli-guides/api-guides/get-started-with-api/

func (*NetlifyDeployer) Check added in v1.5.0

func (d *NetlifyDeployer) Check(ctx context.Context, rep Reporter) (*CheckResult, error)

Check verifies the token can read the configured site.

func (*NetlifyDeployer) Deploy

func (d *NetlifyDeployer) Deploy(ctx context.Context, distDir string, rep Reporter) (*Result, error)

func (*NetlifyDeployer) Name

func (d *NetlifyDeployer) Name() string

type NopReporter added in v1.5.0

type NopReporter struct{}

NopReporter discards everything. Used by the HTTP API path and in tests that do not assert on progress.

func (NopReporter) Log added in v1.5.0

func (NopReporter) Log(string, string)

func (NopReporter) Progress added in v1.5.0

func (NopReporter) Progress(Progress)

func (NopReporter) Step added in v1.5.0

func (NopReporter) Step(Step, string)

type Options added in v1.5.0

type Options struct {
	// ProjectDir is the site root. The GitHub deployer reads the origin
	// remote there; empty means the process working directory.
	ProjectDir string
	// Getenv reads credentials. Nil means os.Getenv; tests inject a map.
	Getenv func(string) string
	// HTTPClient is used by the API deployers. Nil means a default client.
	HTTPClient *http.Client
	// BaseURL overrides the provider API base URL (tests point it at an
	// httptest server). Empty means the provider's public API.
	BaseURL string
}

Options carries everything a deployer needs that is not sarde.yaml config.

type Progress added in v1.5.0

type Progress struct {
	Step       Step
	Done       int
	Total      int
	Bytes      int64
	BytesTotal int64
}

Progress is a snapshot of one step's advance. Done and Total count files; Bytes and BytesTotal are zero when a step does not measure bytes.

type Reporter added in v1.5.0

type Reporter interface {
	Step(s Step, msg string)
	Progress(p Progress)
	Log(level, msg string)
}

Reporter receives a deploy's progress. Deployers never print: everything a user sees goes through a Reporter, so the CLI can render it as human lines or as a machine-readable event stream. Implementations must be safe for concurrent use, because uploads report from several goroutines, and should throttle Progress themselves.

type Result added in v1.5.0

type Result struct {
	Provider      string `json:"provider"`
	URL           string `json:"url,omitempty"`        // live production URL
	DeployURL     string `json:"deploy_url,omitempty"` // permalink of this deploy
	DeployID      string `json:"deploy_id,omitempty"`
	AdminURL      string `json:"admin_url,omitempty"` // provider dashboard for this deploy
	FilesTotal    int    `json:"files_total"`
	FilesUploaded int    `json:"files_uploaded"`
	BytesUploaded int64  `json:"bytes_uploaded"`
}

Result describes a finished deploy.

type Step added in v1.5.0

type Step string

Step names a phase of a deploy. The CLI's JSON reporter sends them to consumers such as Sarde Studio verbatim, so the values are part of the event contract: add new ones, never rename.

const (
	StepCollect  Step = "collect"  // walking the output directory
	StepHash     Step = "hash"     // hashing files
	StepPrepare  Step = "prepare"  // creating the deploy, fetching tokens, project lookups
	StepUpload   Step = "upload"   // sending file contents
	StepFinalize Step = "finalize" // creating the deployment from uploaded files
	StepWait     Step = "wait"     // waiting for the provider to publish
)

type VercelDeployer

type VercelDeployer struct {
	ProjectID string
	TeamID    string
	// contains filtered or unexported fields
}

VercelDeployer publishes a prebuilt site through Vercel's deployments API, using the Build Output API layout so Vercel serves the files as they are and never runs a build of its own. Credentials: the VERCEL_TOKEN environment variable, deploy.project_id (id or name) and, for team-owned projects, deploy.team_id (VERCEL_ORG_ID overrides it).

API reference: https://vercel.com/docs/rest-api/reference/endpoints/deployments/create-a-new-deployment Output layout: https://vercel.com/docs/build-output-api/configuration

func (*VercelDeployer) Check added in v1.5.0

func (d *VercelDeployer) Check(ctx context.Context, rep Reporter) (*CheckResult, error)

Check verifies the token can read the configured project.

func (*VercelDeployer) Deploy

func (d *VercelDeployer) Deploy(ctx context.Context, distDir string, rep Reporter) (*Result, error)

func (*VercelDeployer) Name

func (d *VercelDeployer) Name() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL