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)

20 - Knowledge/devops/git-workflows.md

@@ -0,0 +1,111 @@
+---
+title: Git Workflows
+description: Practical Git workflow patterns for teams and personal infrastructure repositories
+tags:
+  - git
+  - devops
+  - workflow
+category: devops
+created: 2026-03-14
+updated: 2026-03-14
+---
+
+# Git Workflows
+
+## Introduction
+
+A Git workflow defines how changes move from local work to reviewed and deployable history. The right workflow keeps collaboration predictable without adding unnecessary ceremony.
+
+## Purpose
+
+This document covers the most common workflow choices for:
+
+- Application repositories
+- Infrastructure-as-code repositories
+- Self-hosted service configuration
+
+## Architecture Overview
+
+A Git workflow usually combines:
+
+- Branching strategy
+- Review policy
+- Merge policy
+- Release or deployment trigger
+
+The two patterns most teams evaluate first are:
+
+- Trunk-based development with short-lived branches
+- Feature branches with pull or merge requests
+
+## Common Workflow Patterns
+
+### Trunk-based with short-lived branches
+
+Changes are kept small and integrated frequently into the default branch. This works well for active teams, automated test pipelines, and repositories that benefit from continuous deployment.
+
+### Longer-lived feature branches
+
+This can be useful for larger changes or teams with less frequent integration, but it increases drift and merge complexity.
+
+### Infrastructure repositories
+
+For IaC and self-hosting repos, prefer small reviewed changes with strong defaults:
+
+- Protected main branch
+- Required checks before merge
+- Clear rollback path
+- Commit messages that explain operational impact
+
+## Configuration Example
+
+Example daily workflow:
+
+```bash
+git switch main
+git pull --ff-only
+git switch -c feature/update-grafana
+git add .
+git commit -m "Update Grafana image and alert rules"
+git push -u origin feature/update-grafana
+```
+
+Before merge:
+
+```bash
+git fetch origin
+git rebase origin/main
+```
+
+## Troubleshooting Tips
+
+### Merge conflicts happen constantly
+
+- Reduce branch lifetime
+- Split large changes into smaller reviewable commits
+- Rebase or merge from the default branch more frequently
+
+### History becomes hard to audit
+
+- Use meaningful commit messages
+- Avoid mixing unrelated infrastructure and application changes in one commit
+- Document the operational reason for risky changes in the pull request
+
+### Reverts are painful
+
+- Keep commits cohesive
+- Avoid squash-merging unrelated fixes together
+- Ensure deployments can be tied back to a specific Git revision
+
+## Best Practices
+
+- Prefer short-lived branches and small pull requests
+- Protect the default branch and require review for shared repos
+- Use fast-forward pulls locally to avoid accidental merge noise
+- Keep configuration and deployment code in Git, not in ad hoc host edits
+- Align the Git workflow with deployment automation instead of treating them as separate processes
+
+## References
+
+- [Git: `gitworkflows`](https://git-scm.com/docs/gitworkflows)
+- [Pro Git: Branching workflows](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows)