skills/ci-cd-and-automation/SKILL.md
Rama main · réplica de lectura del repositorio original.
---
name: ci-cd-and-automation
description: Use this skill when designing, creating, reviewing, debugging, or improving CI/CD, build pipelines, release workflows, deployment automation, quality gates, artifact publishing, supply-chain security, preview environments, staged rollouts, rollback, or CI feedback loops. It makes the agent behave like a senior release engineer: classify repository and change risk first, build once and promote the same artifact, enforce trustworthy gates, isolate untrusted code, use least privilege and short-lived credentials, preserve provenance, deploy progressively when risk warrants it, observe releases, and make rollback/recovery routine rather than improvised.
metadata:
author: Zelyq
version: "1.0.0"
---
# CI/CD and Release Engineering
## Mission
Build a delivery system that makes the safe path the easy path.
CI/CD is not "a YAML file that runs tests." It is the automated control plane that turns source changes into trusted, reproducible, observable, and recoverable releases.
A strong pipeline should answer:
- What exact source and dependencies produced this artifact?
- Which checks proved it safe enough for this risk level?
- Can untrusted pull-request code reach secrets or privileged runners?
- Are third-party actions and build dependencies trusted and pinned?
- Are cloud credentials short-lived and least-privileged?
- Are we deploying the exact artifact that passed verification?
- Can old and new versions coexist during rollout?
- What happens if deployment succeeds only partially?
- What signals decide whether rollout continues?
- How do we stop, roll back, or roll forward?
- Can an operator reconstruct what happened later?
## Core principles
1. **Classify before configuring.** Repository type and release risk determine gates.
2. **Build once, promote the same artifact.** Do not rebuild independently per environment.
3. **Untrusted code never gets privileged credentials by accident.**
4. **Least privilege is the default.** Scope workflow tokens, environment secrets, and cloud roles narrowly.
5. **Prefer short-lived identity.** Use OIDC/federated identity instead of long-lived cloud keys where supported.
6. **Pin the release inputs.** Lock dependencies and pin third-party Actions/reusable workflows to immutable revisions when feasible.
7. **Provenance matters.** Record commit, build inputs, artifact digest, and attestations for important releases.
8. **Fast feedback and trustworthy feedback both matter.**
9. **Flaky gates are broken gates.** Do not normalize rerun-until-green.
10. **Deployments are state transitions, not file copies.**
11. **Observe the release while it changes production.**
12. **Rollback is designed before failure, not during it.**
13. **Database/configuration changes are part of release engineering.**
14. **Pipeline security is software security.**
15. **Automation reduces toil only when humans can still understand and override it safely.**
## Classify the repository
### Application/service
Load:
- `profiles/application-service.md`
- `references/quality-gates.md`
- `references/deployment-and-progressive-delivery.md`
- `references/observability-and-release-health.md`
### Database-backed service
Also load:
- `profiles/database-backed-service.md`
- `references/database-and-schema-delivery.md`
### Container/image producer
Also load:
- `profiles/container-artifact.md`
- `references/artifacts-provenance-and-supply-chain.md`
### Package/library/SDK
Load:
- `profiles/library-package.md`
- `references/versioning-and-publishing.md`
### Static/public web
Load:
- `profiles/static-web.md`
### Monorepo
Also load:
- `profiles/monorepo.md`
- `references/pipeline-performance-and-cost.md`
### Infrastructure/configuration
Load:
- `profiles/infrastructure-config.md`
- `references/deployment-and-progressive-delivery.md`
### Open-source / fork-heavy repository
Load:
- `profiles/open-source-forks.md`
- `references/workflow-security.md`
## Required workflow
### 1. Inspect before editing
Inspect:
- `.github/workflows/` or equivalent CI configuration;
- package/build manifests and lockfiles;
- test/lint/typecheck/build commands;
- release/publish scripts;
- container definitions;
- database migrations;
- infrastructure-as-code;
- environment/deployment configuration;
- branch/ruleset expectations;
- artifact registry;
- deployment platform;
- current secrets/auth method;
- observability/health checks;
- previous release/rollback conventions.
Do not replace working conventions without a reason.
Run `scripts/ci-audit` when available as a discovery aid. Treat its findings as prompts for review, not complete security proof.
### 2. Define the change path
Map:
```text
source change
↓
verification
↓
build
↓
artifact identity
↓
publish/store
↓
pre-production verification
↓
production rollout
↓
health evaluation
↓
promote / halt / rollback
```
For libraries, replace deployment with versioning/publishing/consumer verification.
### 3. Identify trust boundaries
Explicitly classify workflow inputs as:
- trusted repository code;
- untrusted pull-request/fork code;
- third-party action code;
- dependency/install scripts;
- uploaded/downloaded artifacts;
- cache content;
- environment secrets;
- cloud identity;
- self-hosted runner environment.
For GitHub Actions, privileged triggers such as `pull_request_target` or privileged `workflow_run` flows require special care. Never check out and execute untrusted PR code in a privileged context.
Read `references/workflow-security.md`.
### 4. Design gates by risk
Do **not** force every job onto every change.
Possible gates:
- formatting/lint;
- static/type analysis;
- unit tests;
- integration tests;
- contract/compatibility tests;
- build/package;
- database migration tests;
- E2E;
- security scanning;
- dependency review;
- license policy;
- secret scanning/push protection;
- container/IaC scanning;
- SBOM/provenance/attestation;
- bundle/performance budget;
- accessibility;
- smoke tests;
- deployment health checks.
Use `references/quality-gates.md`.
Cheap, deterministic checks should usually fail quickly. Expensive checks may run in parallel after prerequisites or be scoped by change impact.
### 5. Separate PR validation from privileged release
A pull request from an untrusted fork should be able to prove code quality without receiving production secrets or privileged credentials.
Typical model:
```text
PR/fork
└─ read-only validation
├─ lint/types
├─ tests
└─ build
trusted main/tag
└─ privileged release
├─ build/publish artifact
├─ attest/sign
└─ deploy/promote
```
Do not solve fork CI by exposing secrets to fork jobs.
### 6. Minimize permissions
For GitHub Actions:
- explicitly set `permissions`;
- begin from read-only;
- add write scopes only to jobs that require them;
- give `id-token: write` only where OIDC is needed;
- gate production secrets behind protected environments;
- separate build and deployment credentials.
Do not assume an Action cannot access `github.token` merely because it was not passed explicitly.
### 7. Secure third-party workflow dependencies
For third-party Actions/reusable workflows:
- prefer trusted maintainers;
- pin to a full commit SHA where your policy allows, recording the human-readable release in a comment;
- use dependency automation to keep pins current;
- avoid unnecessary Actions when a small transparent shell step is safer;
- review changes to workflow dependencies like code dependencies.
Never treat `@main` as an immutable release.
### 8. Use reproducible build inputs
Prefer:
- lockfiles;
- pinned tool/runtime versions according to project policy;
- deterministic build configuration;
- clean/ephemeral build environments;
- versioned build tooling;
- controlled external inputs.
Do not let a production artifact depend accidentally on whatever happens to be installed on a runner.
### 9. Build once and identify the artifact
Create one release artifact from one source revision.
Record:
- commit SHA;
- version/build ID;
- artifact digest;
- build time;
- relevant dependency/build metadata.
Publish it to an artifact/package/container registry.
Promote the **same artifact digest** across environments rather than rebuilding source separately for staging and production.
### 10. Preserve provenance and integrity
For important distributable artifacts:
- generate provenance/attestation where the platform supports it;
- attach SBOM where useful/required;
- sign or attest release artifacts according to threat model;
- verify provenance before high-trust deployment where supported.
GitHub Artifact Attestations can establish build provenance for binaries and container images. SLSA provides a model for verifiable build provenance and increasing build integrity.
Read `references/artifacts-provenance-and-supply-chain.md`.
### 11. Authenticate deployments without long-lived cloud keys
Where supported, prefer workload identity/OIDC from CI to the cloud provider.
Scope identity conditions to:
- repository;
- branch/tag;
- workflow;
- environment;
- audience/subject claims
as supported by the provider.
Rotate/remove obsolete static deployment credentials after migration.
### 12. Use environment protections
For sensitive environments:
- restrict deploy branches/tags;
- use required approval only where it reduces risk;
- prevent self-approval where appropriate;
- use environment-specific secrets/variables;
- serialize production deployment when concurrent release mutation is unsafe;
- use automated protection rules tied to observability/security/change-management systems when justified.
Manual approval is not automatically safer. Prefer automated evidence when it is more reliable.
### 13. Handle database/config compatibility
Before deployment determine whether:
- old app + new schema works;
- new app + old schema works during rollout;
- migration locks tables or rewrites large data;
- rollback is possible after data transformation;
- backfills are bounded and observable;
- destructive cleanup must be delayed until old versions disappear.
Prefer expand → migrate/backfill → contract for risky zero-downtime changes.
Read `references/database-and-schema-delivery.md`.
### 14. Deploy progressively when blast radius warrants it
Choose based on risk:
- direct/atomic deployment;
- rolling;
- blue-green;
- canary;
- feature-flagged release;
- region/tenant/cohort staged rollout.
A canary is not merely "deploy to 10%." It requires:
- control/baseline;
- observation period;
- success/failure signals;
- promotion criteria;
- automatic/manual halt;
- rollback path.
Google SRE guidance treats progressive rollout and canary evaluation as a release-safety mechanism.
### 15. Evaluate release health
Observe user and system outcomes during rollout.
Potential signals:
- availability/error rate;
- latency;
- saturation/resource errors;
- queue backlog;
- failed jobs;
- business transaction success;
- client error/crash rate;
- SLO burn rate;
- deployment-specific logs/traces.
Prefer symptoms tied to user impact over noisy internal metrics.
Read `references/observability-and-release-health.md`.
### 16. Roll back first when safety requires it
When a rollout is clearly harming production and rollback is safe:
- halt promotion;
- restore known-good artifact/config;
- verify recovery;
- then diagnose.
Do not improvise an untested hotfix while impact continues if a trusted rollback exists.
Know when rollback is **not** safe, especially after irreversible data migration. In that case, use roll-forward/compensation.
### 17. Make CI feedback useful to agents and humans
On failure:
- preserve full logs;
- upload test reports/screenshots/traces;
- surface concise job summaries;
- distinguish infrastructure failure from product failure;
- include exact failed command/test;
- avoid hiding the first useful error in megabytes of output.
An agent may repair failures, but it must reproduce/verify locally or in an equivalent environment when practical before pushing another attempt.
Do not create an infinite "agent pushes → CI fails → agent pushes" loop.
### 18. Treat flakiness as a defect
When a test intermittently fails:
- record evidence;
- reproduce;
- fix race/time/global-state/network dependence;
- quarantine only with an owner, issue, and deadline when necessary;
- do not make blind retries the normal definition of green.
Retries may be diagnostic or temporarily bounded, not a substitute for reliability.
### 19. Optimize pipeline flow after correctness
Optimize by:
- parallel independent jobs;
- dependency/tool caches with a cache threat model;
- change-aware task selection;
- test sharding;
- build graph/remote cache;
- reusable workflows;
- canceling superseded PR validation;
- right-sized runners;
- avoiding duplicated installs/builds.
Do not impose a universal "under 10 minutes" requirement. Measure:
- time to first useful failure;
- p50/p95 PR feedback;
- queue time;
- total compute cost;
- critical-path duration.
Read `references/pipeline-performance-and-cost.md`.
### 20. Measure delivery outcomes
Track at team/service level when useful:
- change lead time;
- deployment frequency;
- change fail percentage;
- failed-deployment recovery time.
DORA research treats throughput and stability as complementary dimensions, not opposites.
Do not game metrics by splitting meaningless deployments or hiding incidents.
### 21. Final adversarial review
**Trust**
- Can untrusted code reach secrets, write tokens, caches, privileged artifacts, or self-hosted runners?
- Are third-party Actions mutable?
**Artifact**
- Can I prove which source produced production?
- Is production running the same artifact that passed release checks?
**Deployment**
- Can two deployments race?
- Can old/new versions coexist?
- What if rollout stops halfway?
**Data**
- Does rollback still work after migration?
- Can backfill be paused/resumed?
**Detection**
- How will we know within minutes that this release is worse?
- What specific metric halts promotion?
**Recovery**
- Is rollback tested?
- Does rollback restore config/schema compatibility too?
**Pipeline**
- Are flaky tests masking real regressions?
- Is the pipeline so slow people bypass it?
**Security**
- Are cloud credentials long-lived?
- Could a compromised dependency/action modify releases?
## Definition of done
A CI/CD change is done when applicable items are true:
- repository/change risk is classified;
- PR and privileged release trust boundaries are explicit;
- permissions are least-privileged;
- untrusted code cannot access protected credentials;
- quality gates reflect actual project risk;
- build inputs are controlled;
- release artifact has stable identity/digest;
- staging/production promote the same artifact where applicable;
- provenance/SBOM/signing requirements are satisfied where applicable;
- deployment credentials are short-lived when supported;
- production environment protections are appropriate;
- concurrency/race behavior is controlled;
- schema/config compatibility is addressed;
- rollout strategy matches blast radius;
- health signals and promotion criteria exist;
- rollback/roll-forward path exists;
- CI failures provide useful artifacts/logs;
- flaky checks are not normalized;
- pipeline performance is measured and reasonable;
- delivery/recovery can be audited after the fact.
Use `checklists/pipeline-definition-of-done.md` and `checklists/release-definition-of-done.md`.
## Rejection rules
Reject or challenge:
- privileged `pull_request_target` workflows that execute untrusted PR code;
- write-all `GITHUB_TOKEN` permissions by default;
- cloud access keys stored as long-lived repository secrets when OIDC is supported;
- third-party Actions referenced only by mutable branches;
- production deployments from arbitrary branches;
- build-in-production workflows that bypass verified artifacts;
- independent staging and production rebuilds of the same source;
- caches containing secrets or trusted executable state writable by untrusted workflows;
- self-hosted runners exposed to untrusted fork code;
- "rerun until green";
- destructive DB migration + immediate old-code removal in one unsafe step;
- canary without success/failure criteria;
- deployment without observation;
- rollback workflow that has never been exercised;
- security gate consisting only of `npm audit`;
- CI optimized by deleting meaningful tests;
- "manual testing is enough" for repeatable critical checks;
- "manual approval makes it safe" without evidence.
## Context discipline
Load only references relevant to the current repository and release path. Do not turn a simple package-publish workflow into an enterprise deployment platform.