Chapter 1: Why CI/CD isn’t enough
The chapter introduces the promotion gap between CI and CD, why it makes releases risky, and where Kargo fits.
After this chapter you will be able to
- The promotion gap. Explain how promotion differs from CI and CD, and why leaving it improvised creates release risk.
- Kargo control plane role. Describe where Kargo sits in the delivery stack and what it makes explicit about artifact promotion.
- Lumen’s improvised promotion workflow. Trace how Lumen moves an image from CI through pre-prod to production, and explain why this homegrown workflow fills a gap between CI and CD rather than providing a native concept of promotion.
- Hotfix audit evidence gap. Explain why Maya’s successful hotfix could not readily answer what reached production or whether that artifact had passed pre-prod verification, even though its approval was recorded.
- Promotion as a distinct concern. Distinguish the questions CI and CD answer from those a promotion system must answer, and describe the system’s responsibilities at the conceptual level given here.
- Promotion gap diagnostic. Explain how the five questions reveal a promotion gap and why needing to reconstruct their answers manually indicates that the gap remains.
- Change location across environments. Explain why teams struggle to answer whether a fix is in production or how far it has progressed when they lack a model of its movement between environments.
- Hidden hotfix payload. Describe why an urgent production run can carry more than the intended fix, and why the risk grows between releases.
- Known-good rollback state. Explain why rollback needs a named, known-good previous state rather than a mutable tag whose earlier meaning is uncertain.
- Three delivery layer responsibilities. Distinguish the responsibilities of CI, Kargo, and a GitOps agent in the delivery stack.
- Kargo promotion scope and boundaries. Describe what Kargo discovers and records as artifacts move through stages, and state what it does not replace.
- Three promotion gates. Distinguish the three independent gates that govern advancement: an auto-promotion policy, upstream eligibility rules, and approval gates. Explain that Kargo enforces them explicitly rather than relying on team conventions.
- Auditable promotion record. Describe what Kargo records for each promotion and explain that changes to the governing rules are auditable too.
- Queryable artifact lineage. Explain how Kargo can answer what is running in an environment and how it got there by recording precisely identified artifacts, their use and validation across environments, and each promotion transition.
- Pinned artifact identity across environments. Describe how a tag is resolved to a digest when an artifact is discovered and how both travel through promotion. Explain why this avoids relying on a tag that may later point to something else.
- Open source delivery boundary. Explain why open source Kargo alone does not reach workloads on traditional VMs, serverless functions, or platforms without a Kubernetes API.
- Operational cost and fit. Describe when Kargo may be overkill even on Kubernetes and what circumstances make its added control plane worth considering.
- Image discovery and traceability. Explain how Kargo detects a new image version, identifies the exact image behind its tag, and records its progress through promotion.
- Automatic dev promotion. Trace how the new version reaches dev and how Kargo determines that it has been verified there.
- Reviewer gated production promotion. Explain what makes a version eligible for prod and how the production promotion differs from the dev promotion.
Section by section
Introduction
The chapter introduces the promotion gap between CI and CD, why it makes releases risky, and where Kargo fits.
- The promotion gap: Explain how promotion differs from CI and CD, and why leaving it improvised creates release risk.
Why it matters: Separating promotion from building and deployment makes the source of otherwise hidden release risk visible. - Kargo control plane role: Describe where Kargo sits in the delivery stack and what it makes explicit about artifact promotion.
Why it matters: Kargo gives teams a defined place to govern and trace decisions that CI and CD do not model.
Key terms: CI, CD, artifact, promotion, desired state, Kargo, promotion control plane, GitOps agent, stages
1.1 The improvised layer in modern delivery
Lumen’s delivery pipeline shows how improvised promotion can deploy a fix successfully while leaving crucial questions about the release unanswered.
- Lumen’s improvised promotion workflow: Trace how Lumen moves an image from CI through pre-prod to production, and explain why this homegrown workflow fills a gap between CI and CD rather than providing a native concept of promotion.
Why it matters: This workflow explains how a functioning CI/CD stack can still lack a promotion record. - Hotfix audit evidence gap: Explain why Maya’s successful hotfix could not readily answer what reached production or whether that artifact had passed pre-prod verification, even though its approval was recorded.
Why it matters: A fast, apparently successful release is not necessarily one whose contents and testing can be demonstrated later. - Promotion as a distinct concern: Distinguish the questions CI and CD answer from those a promotion system must answer, and describe the system’s responsibilities at the conceptual level given here.
Why it matters: Treating promotion as its own concern makes release decisions and their evidence available from a record instead of a later reconstruction.
Key terms: CI, CD, GitOps repository, pre-prod, production, promotion, hotfix, verification suite, artifact, eligible to advance
1.1.1 A five-question test for the promotion gap
This section uses five questions to test whether an organization can readily verify and govern promotions between CI and CD.
- Promotion gap diagnostic: Explain how the five questions reveal a promotion gap and why needing to reconstruct their answers manually indicates that the gap remains.
Why it matters: The test helps you spot where an improvised delivery process lacks readily available evidence and controls.
Key terms: promotion gap, promotion control plane, separation of duties, artifact lineage
1.1.2 The everyday cost of the promotion gap
The section shows how missing promotion records make routine status checks slow, hotfixes risky, and rollbacks uncertain.
- Change location across environments: Explain why teams struggle to answer whether a fix is in production or how far it has progressed when they lack a model of its movement between environments.
Why it matters: A reliable answer to where a fix stands should not require a fresh manual investigation. - Hidden hotfix payload: Describe why an urgent production run can carry more than the intended fix, and why the risk grows between releases.
Why it matters: Pressure to ship a fix is greatest when knowing what else will ship matters most. - Known-good rollback state: Explain why rollback needs a named, known-good previous state rather than a mutable tag whose earlier meaning is uncertain.
Why it matters: A reversal is dependable only if the team can identify the state it intends to restore.
Key terms: promotion gap, image tags, environments, hotfix, pre-prod, payload, rollback, promotion record, known-good previous state, mutable tag
1.2 Where Kargo fits in the delivery stack
This section places Kargo between CI and a GitOps agent, defining promotion as a distinct responsibility in the delivery stack.
- Three delivery layer responsibilities: Distinguish the responsibilities of CI, Kargo, and a GitOps agent in the delivery stack.
Why it matters: Separating these jobs makes clear which delivery problem Kargo addresses. - Kargo promotion scope and boundaries: Describe what Kargo discovers and records as artifacts move through stages, and state what it does not replace.
Why it matters: These boundaries explain what to expect from Kargo without confusing promotion with building or deployment.
Key terms: CI, promotion, GitOps agent, artifact versions, stages, directed graph, source of truth
1.3 Three capabilities CI and CD don’t provide
1.3.1 Governed promotion
This section explains how Kargo makes promotion governed through three enforced gates and auditable records.
- Three promotion gates: Distinguish the three independent gates that govern advancement: an auto-promotion policy, upstream eligibility rules, and approval gates. Explain that Kargo enforces them explicitly rather than relying on team conventions.
Why it matters: These gates let teams state and enforce different conditions for advancing artifacts into different environments. - Auditable promotion record: Describe what Kargo records for each promotion and explain that changes to the governing rules are auditable too.
Why it matters: The record makes it possible to account for both an advancement and changes to the rules governing it.
Key terms: auto-promotion policy, eligibility rules, approval gates, soaked, promotion, auditable
1.3.2 Queryable lineage
This section explains how Kargo’s artifact and promotion records make deployment history queryable and provide change-control evidence.
- Queryable artifact lineage: Explain how Kargo can answer what is running in an environment and how it got there by recording precisely identified artifacts, their use and validation across environments, and each promotion transition.
Why it matters: It lets you trace a deployed version without piecing together a history from separate sources. - Kubernetes records and evidence: Describe where Kargo keeps its promotion records, how long the trail can persist, and why those records can serve as change-control evidence.
Why it matters: The promotion trail can support change-control questions without a separate record-keeping system, subject to its configured retention.
Key terms: queryable lineage, immutable records, revision identifiers, promotion, Kubernetes objects, garbage-collect, change control, evidence
1.3.3 Immutable artifact identity
This section explains how pinning an artifact to its digest keeps its identity consistent as it moves between environments.
- Pinned artifact identity across environments: Describe how a tag is resolved to a digest when an artifact is discovered and how both travel through promotion. Explain why this avoids relying on a tag that may later point to something else.
Why it matters: Pinning the artifact helps prevent production from quietly receiving something different from what passed pre-prod.
Key terms: tag, digest, promotion pipeline, artifact reference
1.3.4 When Kargo isn’t the right fit
This section explains when open source Kargo is a poor fit, when its operational cost is justified, and how the commercial edition extends its reach.
- Open source delivery boundary: Explain why open source Kargo alone does not reach workloads on traditional VMs, serverless functions, or platforms without a Kubernetes API.
Why it matters: This boundary helps you decide whether the open source edition can serve your production workloads. - Operational cost and fit: Describe when Kargo may be overkill even on Kubernetes and what circumstances make its added control plane worth considering.
Why it matters: A useful promotion system still has to justify the work of operating it. - Commercial edition extension: Distinguish the commercial edition's OpenTofu-aware and custom promotion steps from the open source GitOps handoff, including what changes for delivery outside Kubernetes.
Why it matters: The edition distinction prevents you from assuming that open source Kargo includes these ways to reach other targets.
Key terms: open source Kargo, Kubernetes-based delivery, GitOps agent, control plane, environment, compliance requirements, Kargo Enterprise, OpenTofu-aware promotion steps, custom steps, last-mile action
1.4 Walking a promotion end to end
The section traces one exact demo-app image version from discovery through automatic dev deployment and reviewer-gated production promotion.
- Image discovery and traceability: Explain how Kargo detects a new image version, identifies the exact image behind its tag, and records its progress through promotion.
Why it matters: This makes it possible to follow one specific version through the delivery path. - Automatic dev promotion: Trace how the new version reaches dev and how Kargo determines that it has been verified there.
Why it matters: The dev path shows how an automatic promotion changes GitOps configuration and reaches a verified environment. - Reviewer gated production promotion: Explain what makes a version eligible for prod and how the production promotion differs from the dev promotion.
Why it matters: The production path preserves human approval while keeping the version and its outcome traceable.
Key terms: image repository, tag, exact image, promotion, dev, GitOps repository, manifests, Argo CD, verified, verified in dev
1.5 Summary
Where this is used later
- The core resource model (chapter 3) · Introduces the resources used to represent the promotion model.
- (chapter intro) (chapter 2) · The idea of an improvised layer in modern delivery.
- What Kargo is and where it fits (chapter 3) · The placement of Kargo in the stack provides context for its role alongside other delivery tools.
- Stage: a node in the promotion graph (chapter 3) · The introduction of stages as promotion targets provides context for the Stage resource.
- Defining the Stages (chapter 3) · Defining Stages builds on the idea that advancement can be governed by explicit rules.
- Promotion: a durable advancement event (chapter 3) · The Promotion resource is introduced as a durable advancement event.
- No view of the whole (chapter 2) · The earlier discussion of queryable lineage.
- Freight: an immutable artifact identity (chapter 3) · Provides the reason an immutable artifact identity matters during promotion.
Concepts explained in this chapter
- promotion control planeAn architectural layer that coordinates artifact advancement between environments independently of build and runtime synchronization.
- KargoKargo is an open-source, Kubernetes-native promotion control plane for governing artifact advancement across deployment environments.
- artifact promotionThe controlled advancement of an artifact version from one deployment environment to another.
- promotion recordA promotion record is durable evidence of an artifact's advancement between deployment environments and the decisions associated with that advancement.
- audit trailAn audit trail is a chronological record of actions, decisions, identities, and evidence that permits operational activity to be verified.
- build artifactAn artifact is a deployable unit produced by continuous integration, such as a container image, Helm chart, or rendered manifest bundle.
- governanceGovernance is the set of policies, controls, accountability records, and decision procedures that constrain and document operational changes.
- stageAn explicit environment node in a Kargo promotion progression that represents a deployment state for artifact versions.
- promotion gapA promotion gap is a lack of reliable control, traceability, and evidence connecting a validated artifact to the version running in production.
- artifact identityArtifact identity is the information that uniquely specifies a deployable artifact version, including identifiers such as a digest and provenance data.
- cryptographic hashA digest is a content-derived identifier, typically a cryptographic hash, that uniquely identifies an artifact version.
- rollbackA deployment operation that returns an environment to a previous artifact or application state.
- GitOps operatorA system that continuously compares declared version-controlled state with actual runtime state and applies changes to reconcile them.
- continuous integrationContinuous integration is the practice of automatically building and testing changes and publishing the resulting artifacts.
- progression graphA directed graph representing deployment environments as stages and the governed paths by which artifacts advance between them.
- provenanceA complete, queryable record of an artifact's identity, approvals, verification, and movement across environments.
- separation of dutiesSeparation of duties is a control that distributes approval, execution, and review responsibilities among different people or roles.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
