Documentation
¶
Overview ¶
Package project owns the per-project .citadel/ directory that lives next to citadel.yml: committed metadata (project.yml), the last deploy per env (state/), and per-deploy step logs (runs/). Callers never build paths under .citadel/ themselves.
It is distinct from the global ~/.citadel/ (deployments.db, registry.yml), which holds cross-project data.
Index ¶
- Constants
- func WriteFileAtomic(path string, data []byte) error
- type Dir
- func (d *Dir) EnsureProject(m Meta) (*Meta, bool, error)
- func (d *Dir) NewRun(info RunInfo, term io.Writer) (*Run, error)
- func (d *Dir) Path() string
- func (d *Dir) Project() (*Meta, error)
- func (d *Dir) ReadState(env string) (*State, error)
- func (d *Dir) WriteProject(m Meta) error
- func (d *Dir) WriteState(env string, s State) error
- type Meta
- type Run
- type RunInfo
- type State
- type Step
- type StepRecord
Constants ¶
const ( StatusInProgress = "in_progress" StatusSuccess = "success" StatusFailed = "failed" StatusSkipped = "skipped" )
Run and step statuses written to run.json and state/<env>.json.
const DirName = ".citadel"
DirName is the project directory created next to citadel.yml.
const MaxRuns = 50
MaxRuns is how many run folders NewRun keeps under .citadel/runs/.
Variables ¶
This section is empty.
Functions ¶
func WriteFileAtomic ¶
WriteFileAtomic writes data to path via a temp file in the same directory and a rename, so readers never observe a partially written file and an interrupted write leaves the previous content intact.
Types ¶
type Dir ¶
type Dir struct {
// contains filtered or unexported fields
}
Dir is an opened .citadel/ directory.
func Existing ¶
Existing returns the .citadel/ directory inside configDir without creating anything. The error wraps os.ErrNotExist when there is none.
func Open ¶
Open returns the .citadel/ directory inside configDir, creating it and its .gitignore when missing. It is idempotent and never rewrites an existing .gitignore, so users may add their own lines.
func (*Dir) EnsureProject ¶
EnsureProject returns the existing project.yml, or writes m when there is none. created reports whether m was written.
func (*Dir) NewRun ¶
NewRun creates a new run folder, writes its initial run.json and prunes runs beyond MaxRuns. term receives step output alongside the log files.
func (*Dir) ReadState ¶
ReadState reads state/<env>.json. The error wraps os.ErrNotExist when env has never been deployed from this checkout.
func (*Dir) WriteProject ¶
WriteProject atomically writes project.yml.
type Meta ¶
type Meta struct {
ID string `yaml:"id"`
Name string `yaml:"name"`
Runtime string `yaml:"runtime"`
CreatedAt time.Time `yaml:"created_at"`
CreatedWith string `yaml:"created_with"`
}
Meta is the committed project.yml. Fields may be added over time but never removed; unknown fields are ignored on read.
type Run ¶
type Run struct {
// contains filtered or unexported fields
}
Run records one deploy under .citadel/runs/<id>/: run.json plus one NN-<step>.log per executed step. Logging is best-effort: the first I/O failure prints a single warning to the terminal and the Run carries on writing to the terminal only. A terminal-only Run (TerminalRun) records nothing on disk.
func TerminalRun ¶
TerminalRun returns a Run that sends step output to term only and records nothing on disk. Used for --dry-run and when .citadel/ is unavailable.
func (*Run) Finish ¶
Finish records the outcome in run.json and state/<env>.json, filling st's RunID, Status, GitSHA and times. Only the first call has effect, so callers can both defer it and call it early (e.g. before blocking on log streaming).
type State ¶
type State struct {
RunID string `json:"run_id"`
Status string `json:"status"`
GitSHA string `json:"git_sha"`
ImageURI string `json:"image_uri"`
Target string `json:"target"`
DeployedBy string `json:"deployed_by"`
StartedAt time.Time `json:"started_at"`
FinishedAt time.Time `json:"finished_at"`
}
State is the last deploy of one environment from this checkout, stored in .citadel/state/<env>.json (git-ignored).
Source Files