first version of the knowledge base :)

20 - Knowledge/devops/ci-cd-basics.md

@@ -0,0 +1,112 @@
+---
+title: CI/CD Basics
+description: Introduction to continuous integration and continuous delivery pipelines for application and infrastructure repositories
+tags:
+  - ci
+  - cd
+  - devops
+category: devops
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# CI/CD Basics
+
+## Introduction
+
+Continuous integration and continuous delivery reduce manual deployment risk by automating validation, packaging, and release steps. Even small self-hosted projects benefit from predictable pipelines that lint, test, and package changes before they reach live systems.
+
+## Purpose
+
+CI/CD pipelines help with:
+
+- Fast feedback on changes
+- Repeatable build and test execution
+- Safer promotion of artifacts between environments
+- Reduced manual drift in deployment procedures
+
+## Architecture Overview
+
+A basic pipeline usually includes:
+
+- Trigger: push, pull request, tag, or schedule
+- Jobs: isolated units such as lint, test, build, or deploy
+- Artifacts: build outputs or packages passed to later stages
+- Environments: dev, staging, production, or similar release targets
+
+Typical flow:
+
+```text
+Commit -> CI checks -> Build artifact -> Approval or policy gate -> Deploy
+```
+
+## Core Concepts
+
+### Continuous integration
+
+Every meaningful change should run automated checks quickly and consistently.
+
+### Continuous delivery
+
+Artifacts are always kept in a releasable state, even if production deployment requires a manual approval.
+
+### Continuous deployment
+
+Every validated change is deployed automatically. This is powerful but requires strong tests, rollback paths, and change confidence.
+
+## Configuration Example
+
+GitHub Actions workflow example:
+
+```yaml
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npm test
+```
+
+## Troubleshooting Tips
+
+### Pipeline is slow and developers stop trusting it
+
+- Run fast checks early
+- Cache dependencies carefully
+- Separate heavyweight integration tests from every small change if needed
+
+### Deployments succeed but services still break
+
+- Add health checks and post-deploy validation
+- Make environment-specific configuration explicit
+- Track which artifact version reached which environment
+
+### CI and local results disagree
+
+- Match tool versions between local and CI environments
+- Keep pipeline setup code in version control
+- Avoid hidden mutable runners when reproducibility matters
+
+## Best Practices
+
+- Keep CI feedback fast enough to be used during active development
+- Require checks before merging to shared branches
+- Build once and promote the same artifact when possible
+- Separate validation, packaging, and deployment concerns
+- Treat pipeline configuration as production code
+
+## References
+
+- [GitHub Docs: Understanding GitHub Actions](https://docs.github.com/actions/about-github-actions/understanding-github-actions)
+- [GitHub Docs: Workflow syntax for GitHub Actions](https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax)