CI/CD: guide

# .github/workflows/ci.yml          # шлях до файлу — GitHub шукає workflows саме тут

name: CI Pipeline                   # назва, відображається в UI вкладки Actions

# ─── ТРИГЕРИ ──────────────────────────────────────────────────────────────────
on:                                 # блок "коли запускати цей workflow"

  push:                             # тригер: хтось зробив git push
    branches: [main, develop]       # але тільки якщо push йде в ці гілки
                                    # push у feature/xyz — НЕ запустить workflow

  pull_request:                     # тригер: відкрили / оновили PR
    branches: [main]                # тільки якщо PR цілиться в main
                                    # це запускає CI на кожен новий коміт у PR

  workflow_dispatch:                # тригер: ручний запуск через UI або API
                                    # без параметрів — просто кнопка "Run workflow"

# ─── ГЛОБАЛЬНІ ЗМІННІ ─────────────────────────────────────────────────────────
env:                                # змінні доступні у ВСІХ jobs цього workflow
  REGISTRY: ghcr.io                 # адреса GitHub Container Registry
                                    # ghcr.io — вбудований в GitHub, не треба
                                    # платити за DockerHub або піднімати свій

  IMAGE_NAME: ${{ github.repository }}  # контекст github.repository повертає
                                        # "owner/repo-name", наприклад "andrii/myapp"
                                        # буде використано як частина тегу image

# ─── JOBS ─────────────────────────────────────────────────────────────────────
jobs:                               # список jobs; за замовчуванням виконуються
                                    # ПАРАЛЕЛЬНО, якщо не вказано needs

# ══════════════════════════════════════════════════════════════════════════════
# JOB 1: LINT
# ══════════════════════════════════════════════════════════════════════════════
  lint:                             # ім'я job (довільне, але унікальне в межах workflow)
    runs-on: ubuntu-latest          # тип runner'а; ubuntu-latest = свіжа Ubuntu VM
                                    # GitHub підіймає чисту VM під кожен run
                                    # альтернативи: windows-latest, macos-latest,
                                    # або self-hosted для власних машин

    steps:                          # кроки виконуються ПОСЛІДОВНО зверху вниз

      - uses: actions/checkout@v4   # крок 1: клонує репо в робочу директорію VM
                                    # без цього кроку — файлів коду немає взагалі
                                    # @v4 — закріплена мажорна версія action
                                    # НІКОЛИ не пишіть @latest — сьогодні може
                                    # зламати пайплайн без жодних змін з вашого боку

      - uses: actions/setup-python@v5   # крок 2: встановлює Python на runner
        with:                           # блок параметрів для цього action
          python-version: '3.12'        # яку версію Python встановити
                                        # без цього кроку — береться системний Python
                                        # VM (може бути 3.10 або будь-який інший)

      - run: pip install ruff && ruff check .
        # крок 3: shell команда (bash за замовчуванням)
        # pip install ruff      — встановлює ruff (швидкий Python лінтер на Rust)
        # && ruff check .       — запускає лінтер по всіх .py файлах
        # якщо ruff знайде помилки — повертає exit code != 0
        # ненульовий exit code = крок вважається failed = весь job failed

# ══════════════════════════════════════════════════════════════════════════════
# JOB 2: TEST
# ══════════════════════════════════════════════════════════════════════════════
  test:
    runs-on: ubuntu-latest

    needs: lint                     # ЗАЛЕЖНІСТЬ: цей job стартує тільки після того,
                                    # як job "lint" завершився УСПІШНО
                                    # якщо lint впав — test навіть не стартує
                                    # це заощаджує хвилини runner-часу

    strategy:                       # блок стратегії запуску job
      matrix:                       # matrix = запустити job кілька разів
                                    # з різними комбінаціями змінних
        python-version: ['3.11', '3.12']
        # результат: GitHub створить 2 паралельних job:
        #   test (3.11)
        #   test (3.12)
        # якщо додати ще одну вісь — буде декартовий добуток:
        #   os: [ubuntu, windows] + python: [3.11, 3.12] = 4 jobs

    steps:
      - uses: actions/checkout@v4   # знову клонуємо — кожен matrix job це окрема VM
                                    # стан між jobs НЕ зберігається автоматично

      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          # ${{ matrix.python-version }} — підставляє поточне значення з matrix
          # для першого job = '3.11', для другого = '3.12'
          # так один набір steps працює для всіх версій

      - name: Cache pip              # name — людська назва кроку в UI (опціонально,
                                    # але рятує коли треба знайти де впало)
        uses: actions/cache@v4      # action для кешування директорій між runs
        with:
          path: ~/.cache/pip        # що кешувати: директорія pip cache
                                    # pip завантажені пакети зберігає саме тут

          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
          # ключ кешу — рядок який ідентифікує цей конкретний кеш
          # runner.os       → "Linux" (щоб не мікшувати кеші різних ОС)
          # hashFiles(...)  → SHA256 хеш файлу requirements.txt
          # якщо requirements.txt не змінився — хеш той самий → кеш HIT
          # якщо додали нову залежність → хеш інший → кеш MISS → pip качає заново
          # без кешу: pip install може займати 2-3 хв на кожен run

      - run: pip install -r requirements.txt && pytest --cov
        # pip install -r requirements.txt  — встановлює залежності з файлу
        #   якщо кеш HIT — pip не качає з інтернету, бере локально (секунди)
        #   якщо кеш MISS — качає з PyPI (хвилини)
        # pytest --cov                     — запускає тести з coverage
        #   --cov генерує звіт покриття коду
        #   падіння будь-якого тесту = exit code 1 = job failed

# ══════════════════════════════════════════════════════════════════════════════
# JOB 3: BUILD AND PUSH
# ══════════════════════════════════════════════════════════════════════════════
  build-and-push:
    runs-on: ubuntu-latest

    needs: test                     # стартує тільки після ВСІХ matrix jobs "test"
                                    # тобто і 3.11, і 3.12 мають пройти успішно

    permissions:                    # явне обмеження прав GITHUB_TOKEN для цього job
                                    # за замовчуванням токен може все — це небезпечно
      contents: read                # дозвіл читати код репозиторію (для checkout)
      packages: write               # дозвіл писати в GitHub Packages (ghcr.io)
                                    # без цього рядка docker push поверне 403

    steps:
      - uses: actions/checkout@v4   # клонуємо код — потрібен Dockerfile

      - name: Log in to GHCR        # логінимось у container registry
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}    # ghcr.io (з глобального env вгорі)
          username: ${{ github.actor }}    # github.actor = логін того, хто зробив push
                                           # наприклад "andrii"
          password: ${{ secrets.GITHUB_TOKEN }}
          # GITHUB_TOKEN — спеціальний секрет, який GitHub АВТОМАТИЧНО генерує
          # для кожного workflow run і видаляє після його завершення
          # не треба створювати вручну — він завжди є
          # scope обмежений правами з блоку permissions вище
          # тому packages: write і дає нам право пушити в ghcr.io

      - name: Build and push
        uses: docker/build-push-action@v5  # action для build + push в одному кроці
        with:
          push: ${{ github.ref == 'refs/heads/main' }}
          # умовний push: будуємо image завжди, але пушимо ТІЛЬКИ якщо
          # це push у гілку main (refs/heads/main)
          # якщо це PR або push у develop — push: false
          # навіщо: в PR хочемо перевірити що image будується без помилок,
          # але не забруднювати registry тимчасовими образами

          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
          # фінальний тег image, наприклад:
          # ghcr.io/andrii/myapp:a3f8c91d...
          #
          # env.REGISTRY    → ghcr.io
          # env.IMAGE_NAME  → andrii/myapp
          # github.sha      → повний SHA коміту (40 символів)
          #
          # чому SHA, а не latest?
          # SHA незмінний — завжди можна знайти який коміт в якому image
          # latest постійно перезаписується — важко відкотити і дебажити

deploy:
  environment:
    name: production
    url: https://myapp.com    # відображається в UI
  steps:
    - run: ./deploy.sh

jobs:
  call-deploy:
    uses: org/shared-workflows/.github/workflows/deploy.yml@main
    with:
      environment: production
    secrets: inherit

# .github/actions/setup-app/action.yml
name: Setup App
runs:
  using: composite
  steps:
    - uses: actions/setup-node@v4
      with:
        node-version: '20'
    - run: npm ci
      shell: bash

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true   # скасовує попередній run при новому push

// Jenkinsfile
pipeline {
    agent {
        docker {
            image 'node:20-alpine'
            args '-v /var/run/docker.sock:/var/run/docker.sock'
        }
    }

    environment {
        DOCKER_REGISTRY = 'registry.example.com'
        APP_NAME        = 'my-app'
    }

    options {
        timeout(time: 30, unit: 'MINUTES')
        buildDiscarder(logRotator(numToKeepStr: '10'))
        disableConcurrentBuilds()
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Lint & Test') {
            parallel {
                stage('Lint') {
                    steps {
                        sh 'npm run lint'
                    }
                }
                stage('Unit Tests') {
                    steps {
                        sh 'npm test -- --coverage'
                    }
                    post {
                        always {
                            junit 'test-results/**/*.xml'
                            publishCoverage adapters: [coberturaAdapter('coverage/cobertura-coverage.xml')]
                        }
                    }
                }
            }
        }

        stage('Build Docker Image') {
            steps {
                script {
                    def image = docker.build("${DOCKER_REGISTRY}/${APP_NAME}:${BUILD_NUMBER}")
                    docker.withRegistry("https://${DOCKER_REGISTRY}", 'registry-credentials') {
                        image.push()
                        image.push('latest')
                    }
                }
            }
        }

        stage('Deploy to Staging') {
            steps {
                sh './scripts/deploy.sh staging ${BUILD_NUMBER}'
            }
        }

        stage('Integration Tests') {
            steps {
                sh 'npm run test:e2e -- --base-url https://staging.example.com'
            }
        }

        stage('Deploy to Production') {
            when {
                branch 'main'
            }
            input {
                message 'Deploy to production?'
                ok 'Deploy'
                submitter 'admin,devops-team'
            }
            steps {
                sh './scripts/deploy.sh production ${BUILD_NUMBER}'
            }
        }
    }

    post {
        success {
            slackSend channel: '#deployments', color: 'good',
                      message: "✅ ${JOB_NAME} #${BUILD_NUMBER} succeeded"
        }
        failure {
            slackSend channel: '#deployments', color: 'danger',
                      message: "❌ ${JOB_NAME} #${BUILD_NUMBER} failed: ${BUILD_URL}"
        }
        always {
            cleanWs()   // очищаємо workspace після кожного запуску
        }
    }
}

// vars/deployToKubernetes.groovy
def call(Map config) {
    sh """
        helm upgrade --install ${config.releaseName} ${config.chart} \
          --namespace ${config.namespace} \
          --set image.tag=${config.imageTag}
    """
}

// Jenkinsfile
@Library('company-shared-library') _

pipeline {
    stages {
        stage('Deploy') {
            steps {
                deployToKubernetes(
                    releaseName: 'my-app',
                    chart: './helm/my-app',
                    namespace: 'production',
                    imageTag: env.BUILD_NUMBER
                )
            }
        }
    }
}

# GitHub Actions: правильний ключ кешу
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-   # fallback: використовуємо застарілий кеш      

jobs:
  build:
    steps:
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist-files
          path: dist/
          retention-days: 7

  deploy:
    needs: build
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist-files
          path: dist/
      - run: ./deploy.sh

permissions:
  id-token: write   # дозвіл на отримання OIDC token

steps:
  - uses: aws-actions/configure-aws-credentials@v4
    with:
      role-to-assume: arn:aws:iam::123456789:role/GitHubActionsRole
      aws-region: us-east-1
      # Немає жодних ключів! GitHub отримує тимчасові credentials через OIDC

# Погано — значення потрапить у лог
- run: echo "Token is ${{ secrets.API_TOKEN }}"

# Добре — маскується як ***
- run: |
    echo "::add-mask::$MY_TOKEN"
    ./deploy.sh    
  env:
    MY_TOKEN: ${{ secrets.API_TOKEN }}

# Приклад з Argo Rollouts
spec:
  strategy:
    canary:
      steps:
        - setWeight: 5      # 5% трафіку на нову версію
        - pause: {duration: 10m}
        - setWeight: 20
        - pause: {duration: 10m}
        - setWeight: 100

spec:
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1         # max нових pods понад desired
      maxUnavailable: 0   # жоден pod не може бути недоступний

# Helm
helm rollback my-app 2   # відкат до revision 2
helm history my-app      # переглянути всі ревізії

# Kubernetes
kubectl rollout undo deployment/my-app
kubectl rollout undo deployment/my-app --to-revision=3

git revert HEAD~1 --no-edit
git push origin main   # тригерить CI/CD

# GitHub Actions: сповіщення в Slack при падінні на main
- name: Notify Slack on failure
  if: failure() && github.ref == 'refs/heads/main'
  uses: slackapi/slack-github-action@v1
  with:
    channel-id: 'C012AB3CD'
    payload: |
      {
        "text": "❌ Pipeline failed on main",
        "blocks": [{
          "type": "section",
          "text": {
            "type": "mrkdwn",
            "text": "*Job:* ${{ github.job }}\n*Run:* ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          }
        }]
      }      
  env:
    SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-app
  namespace: argocd
spec:
  project: default
  source:
    repoURL: https://github.com/company/k8s-manifests
    targetRevision: HEAD
    path: apps/my-app/overlays/production
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true      # видаляти ресурси, яких немає в Git
      selfHeal: true   # відновлювати при ручних змінах у кластері

# GitHub Actions
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    if: github.event_name == 'push'   # не запускати в PR
    steps:
      - run: ./deploy.sh

# GitHub Actions
jobs:
  test:
    timeout-minutes: 15   # весь job не більше 15 хвилин
    steps:
      - run: pytest
        timeout-minutes: 10   # конкретний step

# Jenkins Declarative
options {
    timeout(time: 30, unit: 'MINUTES')
}

strategy:
  matrix:
    os: [ubuntu-latest, windows-latest]
    python-version: ['3.11', '3.12']
  fail-fast: false   # не зупиняти інші runs при падінні одного

on:
  push:
    paths:
      - 'services/user-service/**'
      - 'shared-libs/**'

jobs:
  detect-changes:
    outputs:
      services: ${{ steps.changed.outputs.services }}
    steps:
      - id: changed
        run: |
          SERVICES=$(./scripts/detect-changed-services.sh)
          echo "services=$SERVICES" >> $GITHUB_OUTPUT          

  build:
    needs: detect-changes
    strategy:
      matrix:
        service: ${{ fromJson(needs.detect-changes.outputs.services) }}

# GitHub Actions: retry всього job при флакі
- uses: nick-fields/retry@v3
  with:
    timeout_minutes: 10
    max_attempts: 3
    command: npm test

- name: Scan image with Trivy
  uses: aquasecurity/trivy-action@master
  with:
    image-ref: myapp:${{ github.sha }}
    format: sarif
    output: trivy-results.sarif
    severity: 'CRITICAL,HIGH'
    exit-code: '1'   # зламати пайплайн при знахідці

- name: Upload to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: trivy-results.sarif

- uses: docker/build-push-action@v5
  with:
    cache-from: type=gha           # GitHub Actions cache
    cache-to: type=gha,mode=max

lifecycle:
  preStop:
    exec:
      command: ["/bin/sh", "-c", "sleep 15"]

spec:
  minAvailable: 2
  selector:
    matchLabels:
      app: my-app