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
- func ErrorCode(err error) string
- type APIError
- type CheckResult
- type Checker
- type CloudflareDeployer
- type CustomDeployer
- type Deployer
- type File
- type GitHubPagesDeployer
- type NetlifyDeployer
- type NopReporter
- type Options
- type Progress
- type Reporter
- type Result
- type Step
- type VercelDeployer
Constants ¶
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.
const ( LevelInfo = "info" LevelWarn = "warn" )
Log levels for Reporter.Log.
Variables ¶
This section is empty.
Functions ¶
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.
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
func (d *CloudflareDeployer) Check(ctx context.Context, rep Reporter) (*CheckResult, error)
Check looks the project up and fetches an upload token: it proves both read and write access and uploads nothing.
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) 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
func (d *GitHubPagesDeployer) Check(ctx context.Context, rep Reporter) (*CheckResult, error)
Check verifies the origin remote is reachable with the current git credentials (`git ls-remote`, read-only).
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) 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
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
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) Name ¶
func (d *VercelDeployer) Name() string