Module 1: Why Cicd And Gitops
1. Introduction to the guide: from the terminal to the pipeline
Description
If you completed terraform-and-iac-guide, you already know how to declare infrastructure. The andes-cargo-infra/ project exists, with its s3-bucket and iam-role modules, and with Andes Cargo's four canonical resources —the andes-cargo-shipment-docs bucket, the Shipments table, the LambdaManifestProcessorRole and AppServerRole roles, and the process-shipment-manifest function— declared in HCL. You know how to read a plan, you know why state is the source of truth, and you've run terraform apply more times than you can count. There's an exact phrase that opened that guide, and this guide fulfills it: "first you understand what each command does, then you automate it." You already understood what apply does. This guide teaches you to stop typing it yourself.
This guide —CI/CD and GitOps on AWS— doesn't declare a single new business resource. There's no fifth piece of Andes Cargo. What changes, again, is the method: instead of a person typing terraform apply from their laptop, a pipeline is going to do it for them —after someone else reviewed the change, and only once that change reached the main branch through a pull request, not by accident. By the end of this guide you're going to have a real repository where a git push automatically triggers fmt, validate, and plan; where the plan is what gets reviewed before merging; and where apply runs on its own, without anyone typing it, exactly against the plan that was approved.
Connection to the module
This Module 1 has the same job as the first module of terraform-and-iac-guide: build the bridge. Lessons 2 to 5 name, precisely, the real problem with manual apply (not in the abstract — in the exact terms of what you already lived through), define what CI is versus CD-delivery versus CD-deployment, what GitOps is, and why this guide chooses GitHub Actions among several real market alternatives. Lessons 6 and 7 are pure hands-on: you install act —the tool that's going to run every workflow in this guide in Docker, on your machine, for free— and you run your first workflow end to end. Lesson 8, this module's project, prepares andes-cargo-infra/ to receive its first real pipeline: it initializes it as a Git repository if needed, creates .github/workflows/, and leaves LocalStack running. With that, you enter Module 2 with all the ground prepared to write the first workflow that actually touches Andes Cargo.
What this guide assumes (and doesn't re-explain)
This guide is not an entry point to Terraform or AWS. It assumes, without re-explaining it, everything you built in terraform-and-iac-guide (and, transitively, in aws-core-services-guide):
- You know what HCL is, what
resource/variable/output/localsdo, and what theandes-cargo-infra/project looks like on the inside — because you wrote it, module by module, all the way to its capstone. - You know what Terraform
stateis, why it's the source of truth, and what happens if twoapplyruns touch it at the same time. - You know what LocalStack is, how to bring it up with Docker, and why the account ID
000000000000shows up in every ARN in your lab. - You can navigate Git at the usage level:
init,add,commit,branch,merge,revert— fromgit-github-guide, linked, not re-taught here.
If anything on that list doesn't feel solid, that's the signal to go back to the corresponding guide before continuing — no lesson from here on re-explains what a Terraform resource is or how to resolve a merge conflict, only how to automate them inside a pipeline.
What this guide does teach, and none of the previous ones covered on purpose: continuous integration (CI) versus continuous delivery and continuous deployment (the two faces of "CD"); GitOps as a principle; the complete anatomy of a GitHub Actions workflow; HashiCorp/GitHub's standard pattern for IaC in CI/CD; secrets management and OIDC federation; environments and approvals; scheduled drift detection; the infrastructure rollback pattern; and branch protection.
The complete map: the 8 modules of this guide
CI/CD AND GITOPS ON AWS — THE 8 MODULES
M1 Why CI/CD and GitOps ← you are here: installing act, first workflow
M2 Anatomy of a workflow complete YAML syntax, act -e, secrets
M3 The IaC pipeline fmt/validate/plan on every PR (half of CI)
M4 Secrets, environments and identity GitHub Secrets, OIDC (named), dev/prod
M5 Apply on merge chained apply.yml, concurrency, drift
M6 Rollback and safety nets git revert, branch protection, guardrail
M7 GitOps beyond Terraform Jenkins/GitLab CI, ArgoCD/Flux (named)
M8 Capstone: the complete pipeline a real change and a rejected change| # | Module | What it builds | Piece of the Andes Cargo pipeline |
|---|---|---|---|
| 1 | Why CI/CD and GitOps | act installed, first workflow run end to end | (preparation — empty .github/workflows/, zero business YAML) |
| 2 | Anatomy of a workflow | on/jobs/steps/runs-on/uses, simulating events and secrets with act | hello-andes-cargo.yml, the first real Action connecting to the runner |
| 3 | The IaC pipeline | fmt/validate/plan as CI steps, the plan as review evidence | Complete ci.yml |
| 4 | Secrets, environments and identity | GitHub Secrets, named OIDC, dev/prod as Environments | Andes Cargo's secrets/environments plan |
| 5 | Apply on merge | apply.yml triggered by push to main, needs, concurrency, schedule | apply.yml + drift.yml |
| 6 | Rollback and safety nets | git revert on HCL, branch protection, a real guardrail on the plan | The guardrail protecting the Shipments table |
| 7 | GitOps beyond Terraform | Contrast with Jenkins/GitLab CI, push vs. pull, boundary with app CI/CD | Andes Cargo's tooling ADR |
| 8 | Capstone | The complete pipeline, tested with a real change and a rejected one | andes-cargo-infra/ with .github/workflows/ as a portfolio deliverable |
Notice the progression: first you learn why and what tool you're going to test it with for free (M1-M2), then you build half of CI (M3), then who can apply what and with which key (M4), only then half of CD (M5), and you close with the safety nets (M6) and the broader landscape (M7) before the capstone (M8).
This module's map: the 8 lessons
| # | Lesson | What you practice |
|---|---|---|
| 1 | Introduction (this one) | The complete map, what's inherited from terraform-and-iac-guide, what's genuinely new |
| 2 | The problem with manual apply | Honest recap: who ran it? with what credentials? what happens if that person isn't there? |
| 3 | CI, CD, and CD: three things, one acronym | Continuous integration vs. continuous delivery vs. continuous deployment |
| 4 | What is GitOps | Origin of the term, Git as the source of truth, the principle, not the tool |
| 5 | GitHub Actions and its alternatives | GitLab CI, CircleCI, Jenkins, with market honesty |
| 6 | Hands-on: installing act | Executed: act --version, .actrc, Docker verified |
| 7 | Hands-on: your first local workflow | Executed: a "hello world" run end to end with act |
| 8 | Project: bootstrapping Andes Cargo's pipeline | Executed: andes-cargo-infra/ as a Git repo, .github/workflows/ created, LocalStack up |
The one genuinely new thing: pipeline-layer artifacts
This guide does not invent a new business case, and it doesn't declare a single new business HCL resource either. The four resources you already know from Andes Cargo remain, name for name, the same: the andes-cargo-shipment-docs bucket, the Shipments table, the LambdaManifestProcessorRole and AppServerRole roles, and the process-shipment-manifest function. The example shipments remain the same three: 4471 Peru→Chile, 4472 Colombia→Ecuador, 4473 Chile→Peru. Same account 000000000000, same region us-east-1.
The only new things are artifacts in the pipeline layer, never business ones, always in English:
.github/workflows/ci.yml(plan on PR, Module 3),apply.yml(apply on merge, Module 5),drift.yml(scheduled detection, Module 5)..actrcat the root of the repository — the pinned runner image, and later a network flag to talk to LocalStack..github/act-events/pr-event.jsonandpush-event.json— these aren't a GitHub standard, they're specific to this guide, for simulating events withact -ewithout needing a real account (Module 2)..secrets— gitignored from the exact moment it appears (Module 2) — with LocalStack's dummytest/testcredentials.- A pipeline
README.mdinsideandes-cargo-infra/, the capstone's portfolio deliverable (Module 8).
None of this replaces Andes Cargo's four canonical names. When Module 3 runs terraform plan inside a workflow, the bucket that plan describes is still going to be called andes-cargo-shipment-docs — now inside a YAML step, not a terminal.
A note on a clean start: two dependencies, not one
terraform-and-iac-guide already taught you that LocalStack's Hobby plan doesn't persist resources between container restarts, and that this guide doesn't assume your previous session is still alive. This guide inherits that same precaution, with one extra layer: besides Docker running LocalStack, you now also need Docker running the ephemeral containers that act creates to simulate each GitHub Actions job. These are different uses of the same Docker —LocalStack is a long-lived container you start once and leave running; act's containers are ephemeral, one new one per job run, that destroy themselves when done. Lesson 6 of this module verifies both uses separately, before mixing them.
The $0 commitment, with one more piece: act
Terraform against LocalStack already cost you $0. GitHub Actions, run on GitHub's real hosted runners, has limited free minutes and then bills per minute — but this guide never uses those runners. act (nektos/act) executes the same YAML that would run on github.com, in Docker, on your machine, without touching any hosted runner or requiring a GitHub account. It's $0 for the same reason LocalStack is: the real work happens in a container you control, not in a provider's infrastructure that bills you by usage.
You're going to install it in lesson 6 of this module and run your first workflow with it in lesson 7 — with real output, not a prose simulation.
What DOES run, and what's representative (the full honesty, from the start)
This guide holds the same hard rule as terraform-and-iac-guide: nothing is simulated in prose; if a workflow appears in a lesson, it ran with act to write it. There are exactly five exceptions, each with an exact, researched and verified technical reason —not an assumed limitation— and each labeled at the exact moment it appears, never hidden:
| Doesn't run here | Why (exact technical reason) | Where it appears, labeled |
|---|---|---|
| Federated OIDC to real AWS | act doesn't implement OIDC token issuance; there's also no real AWS account to federate against | Module 4 |
| Environments with required approval | act ignores environment: for protection purposes — it runs the job anyway, without waiting for approval (open nektos/act issue) | Module 4 |
| Branch protection rules | It's repository configuration, not a workflow — there's no YAML for act to execute | Module 6 |
Commenting the plan on a real PR | Requires a real PR with a number assigned by GitHub | Module 3 (with its real executable equivalent: $GITHUB_STEP_SUMMARY) |
| Hosted runners / real GitHub account | Outside this guide's $0 scope by design | Module 8 |
Everything else —including all three complete Andes Cargo workflows (ci.yml, apply.yml, drift.yml) and Module 6's guardrail— really runs, with act, against the same LocalStack you already know.
What you WON'T see in this guide
So you know what to expect from the start: this guide does not build Kubernetes' pull-based GitOps with ArgoCD or Flux (that's kubernetes-and-eks-in-production-guide — they're named here, in Module 7, for contrast), it doesn't build end-to-end OIDC against a real AWS account or SAST/supply-chain (cloud-security-and-guardrails-guide), it doesn't teach application code CI/CD —tests, build, deploying an artifact— beyond a short, deliberate contrast (cicd-python-backend-guide, testing-in-cicd-guide), it doesn't build application deployment strategies like blue/green or canary (kubernetes-and-eks-in-production-guide, aws-serverless-and-containers-guide), and it doesn't cover SRE for the pipeline itself —SLOs, on-call, postmortems— (sre-and-incident-response-guide). Every apply in this guide keeps running against LocalStack, with act, on purpose: first you understand the complete pipeline in a $0, reproducible lab, then —in another guide— you take it against a real account.
Common mistakes
Assuming this module is going to declare a new Andes Cargo resource (expectation-based). What happens: someone who already did terraform-and-iac-guide expects to see a fifth AWS service, or a bigger architecture. Why it happens: it's the pattern other guides in the ecosystem followed, where each new guide did expand the business case. How to spot it: if you're looking for "what new HCL resource are we going to write?" instead of "how is the same apply going to run without me typing it?". How to fix it: this guide's value isn't in a new resource — it's, again, in the method. You end up with exactly the same four resources as always, now applied by a pipeline.
Believing act is "almost like" GitHub Actions, an approximation (conceptual). What happens: someone assumes act is a simulator that interprets YAML approximately, and that what runs there isn't "really" a GitHub Actions workflow. Why it happens: the word "local" sounds, by default, like "simplified." How to spot it: if you think the .github/workflows/ci.yml you're going to write in this guide would need to be rewritten to run in a real GitHub repository. How to fix it: it doesn't need to change a single line — act executes the same YAML, with the same real Marketplace Actions, inside Docker. What changes isn't the workflow, it's who triggers the event (you, by hand, instead of GitHub) and where the container runs (your machine, instead of a hosted runner).
Skipping terraform-and-iac-guide because "this is just YAML" (flow-based). What happens: someone with no prior Terraform experience tries to start directly here, and runs into a step that runs terraform plan without understanding what that output means. Why it happens: a CI/CD workflow is, on the surface, "just YAML" — but that YAML orchestrates Terraform commands this guide takes for granted. How to spot it: if a word like "state" or "provider" is unfamiliar to you in Module 3. How to fix it: go back to terraform-and-iac-guide. This guide teaches when and who runs terraform apply, not what each Terraform command does.
Exercises
Exercise 1 — Translate the change of method into your own words. Without using the terms "CI," "CD," or "GitOps" yet (you're going to formalize them in lessons 3 and 4), describe in two or three sentences what, concretely, changes between finishing terraform-and-iac-guide and finishing this guide.
See solution
A complete answer sounds, roughly, like this: "In terraform-and-iac-guide, I was the only person standing between the HCL code and real infrastructure: I typed terraform plan, I read it, I typed apply. In this guide, that same plan and that same apply are run automatically by a pipeline when I do a git push or when a change gets merged into main — the code stays the same, the resulting infrastructure stays the same, but it's no longer me, from my terminal, deciding in the moment to run the command: the process is defined ahead of time, in a versioned file, not in my memory of which command was next." The key piece: the HCL doesn't change — who and when applies it does.
Exercise 2 — Locate the five representative exceptions. Without looking back at this lesson, name from memory the five things this guide does not execute with act, and in which module each one appears.
See solution
Module 3: commenting the plan directly on a real Pull Request (the real available equivalent runs instead: $GITHUB_STEP_SUMMARY). Module 4: federated OIDC to real AWS, and Environments with required approval. Module 6: branch protection rules. Module 8: anything that depends on hosted runners or a real GitHub account. If you remembered all five and which of "OIDC not implemented by act," "environment: ignored by act," "it's repository configuration, not YAML," "needs a real PR," and "outside the $0 scope" matches each one, you have a clear grasp of this guide's execution honesty.
Exercise 3 — The $0 commitment, at the CI/CD layer. A colleague who already knows how LocalStack's $0 works asks you: "Don't I need a GitHub account and Actions minutes to learn this?" Answer them in two or three sentences, explaining why the answer is no.
See solution
A complete answer sounds, roughly, like this: "No — act executes the same YAML from a GitHub Actions workflow inside Docker containers on your own machine, without touching any GitHub hosted runner or requiring an account. The only real cost is the same one you already had with LocalStack: Docker running on your computer. The only things I can't show you with this setup are five very specific things —like the real approval of an Environment— that depend, by design, on a real GitHub account; all of them are named and explained here, none is hidden."
Summary and next step
In this lesson you saw the complete map of this guide's 8 modules, confirmed what's inherited without repeating from terraform-and-iac-guide (Andes Cargo's four resources, the state, LocalStack, the $0 commitment), and what's genuinely new (CI/CD, GitOps, the anatomy of a workflow, secrets and named OIDC, environments, rollback, branch protection). You also saw, in a complete table, exactly which five things this guide doesn't execute with act and why —execution honesty declared from the first module, not discovered halfway through.
Before moving on you should be able to: name the four resources inherited from Andes Cargo; explain in one sentence what changes between terraform-and-iac-guide and this guide (the method, not the outcome); and name the five representative exceptions and their technical reason.
What's still missing is naming the problem precisely. Lesson 2 returns, with full honesty, to the exact moment where manual apply starts to really hurt — with a question terraform-and-iac-guide never made you answer.
Resources
- GitHub Docs — GitHub Actions — the official documentation for the tool you install and use throughout this guide.
- nektosact.com — User Guide — the official documentation for
act, the $0 tool that runs these workflows on your machine. terraform-and-iac-guide(NIEVA) — this guide's complete prerequisite: HCL, theinit/plan/apply/destroycycle, thestate, and theandes-cargo-infra/project, all assumed and not re-explained here.src/paths/aws-cloud-ecosystem/VALIDACION.md(NIEVA, market audit, Jul-2026) — the evidence motivating this guide: CI/CD as the ecosystem's most cited gap, 13 of 13 offerings read.