Documentation
¶
Overview ¶
Package environments emits a per-environment configuration file an operator applies to GitHub's Environments REST API. cascade EMITS the file; the operator APPLIES it (gh api / Terraform). cascade never calls the GitHub API.
The emitted artifact is a small wrapper:
{
"environments": [ { ... }, { ... } ] // one entry per manifest environment,
// in the manifest's environments order
}
Each entry pairs the directly-appliable Environments REST body with companion operator guidance:
{
"name": "prod", // the cascade environment name
"gha_environment": "production",// the GitHub Environment to configure
"environment": { ... }, // the body to PUT to the environments API
"operator_todo": { ... } // guidance that is NOT part of the PUT body
}
The split mirrors the branch-protection command. The "environment" object is the exact body for
PUT /repos/{owner}/{repo}/environments/{gha_environment}
for the fields cascade can fully form from the manifest (wait_timer and deployment_branch_policy). Required reviewers are surfaced under operator_todo, not inside "environment": the REST API requires a numeric reviewer id, and the manifest carries only slugs, so the operator resolves each slug to an id before adding it. Expected env-scoped secret and variable NAMES are also operator guidance: they are created through the separate environment-secrets and environment-variables APIs, and cascade emits names only, never values.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal renders the payload as indented JSON with exactly one trailing newline. The same manifest always produces byte-identical output: the environment order follows the manifest, and every emitted struct field has a stable JSON key order.
func NewCommand ¶
NewCommand creates the environments command. It emits a per-environment configuration file an operator applies to GitHub's Environments REST API. cascade emits the file; the operator applies it. cascade never calls the GitHub API.
Types ¶
type DeploymentBranchPolicy ¶
type DeploymentBranchPolicy struct {
ProtectedBranches bool `json:"protected_branches"`
CustomBranchPolicies bool `json:"custom_branch_policies"`
}
DeploymentBranchPolicy mirrors GitHub's deployment_branch_policy object. Exactly one of ProtectedBranches and CustomBranchPolicies is true; GitHub rejects a body where both are equal.
type Environment ¶
type Environment struct {
// Name is the cascade environment name (from the manifest environments list).
Name string `json:"name"`
// GHAEnvironment is the GitHub Environment to configure. It defaults to Name
// when the manifest does not set environment_config.<name>.gha_environment.
GHAEnvironment string `json:"gha_environment"`
// Environment is the body to PUT to the environments REST API.
Environment EnvironmentBody `json:"environment"`
// OperatorTodo is companion guidance, NOT part of the PUT body.
OperatorTodo OperatorTodo `json:"operator_todo"`
}
Environment is the per-environment config block. "environment" is the exact PUT body for the fields cascade can form from the manifest; "operator_todo" is sibling guidance that must never be sent to GitHub verbatim.
type EnvironmentBody ¶
type EnvironmentBody struct {
// WaitTimer is the deploy delay in minutes (0..43200). It is always emitted
// so the body is byte-stable; 0 means no wait.
WaitTimer int `json:"wait_timer"`
// DeploymentBranchPolicy selects which branches may deploy. A nil pointer
// marshals to null, GitHub's "all branches" value.
DeploymentBranchPolicy *DeploymentBranchPolicy `json:"deployment_branch_policy"`
}
EnvironmentBody is the body an operator PUTs to /repos/{owner}/{repo}/environments/{environment_name}. Only the fields cascade can fully form from the manifest appear here. Reviewers are omitted on purpose (the API needs numeric ids; see OperatorTodo.RequiredReviewers).
type OperatorTodo ¶
type OperatorTodo struct {
// Note is human guidance describing how to apply this entry.
Note string `json:"note"`
// RequiredReviewers lists the user or team slugs to add as reviewers. The
// REST API needs each reviewer's numeric id, which the manifest does not
// carry, so the operator resolves these slugs to ids before applying.
RequiredReviewers []string `json:"required_reviewers,omitempty"`
// BranchPatterns lists branch name patterns to create as
// deployment-branch-policies (custom policy only).
BranchPatterns []string `json:"branch_patterns,omitempty"`
// TagPatterns lists tag name patterns to create as deployment-branch-policies
// of type tag (custom policy only).
TagPatterns []string `json:"tag_patterns,omitempty"`
// Secrets lists the EXPECTED env-scoped secret NAMES to create through the
// environment-secrets API. Names only, never values.
Secrets []string `json:"secrets,omitempty"`
// Variables lists the EXPECTED env-scoped variable NAMES to create through
// the environment-variables API. Names only, never values.
Variables []string `json:"variables,omitempty"`
}
OperatorTodo is companion guidance emitted alongside the PUT body. It is NOT accepted by the environments PUT endpoint and must be applied through the steps it describes rather than sent to GitHub verbatim.
type Options ¶
type Options struct {
// ConfigPath is the manifest path; empty means auto-detect.
ConfigPath string
// ManifestKey is the key in the manifest file holding the CI config.
ManifestKey string
// Output is the destination path. Empty or "-" writes to stdout.
Output string
}
Options configures an environments emit run.
type Payload ¶
type Payload struct {
Environments []Environment `json:"environments"`
}
Payload is the full emitted artifact: one entry per manifest environment, in the manifest's environments order.
func Build ¶
func Build(cfg *config.TrunkConfig) Payload
Build assembles the Payload from a resolved manifest. It walks cfg.Environments in order so the output is stable and matches the manifest's declared environment order. For each environment it reads the optional environment_config.<name> block; an absent block yields an entry whose gha_environment defaults to the environment name, an empty wait timer, an "all branches" policy, and no reviewers, secrets, or variables.
Source Files