> ## Documentation Index
> Fetch the complete documentation index at: https://infra-docs.kaeyros.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Pipelines GitHub Actions : build, test, publish

> Structure des workflows CI/CD GitHub Actions pour les dépôts applicatifs Kaeyros. Build, tests, SAST et publication d'images Docker vers ghcr.io.

Chaque dépôt applicatif chez Kaeyros Analytics dispose d'un workflow GitHub Actions qui automatise la construction, les tests et la publication des images Docker. Le fichier `.github/workflows/ci.yml` est le contrat standard partagé par tous les services backend et frontend.

## Structure du workflow type

Le workflow est déclenché sur chaque push et chaque pull request. Il s'adapte automatiquement à la branche cible pour produire le bon tag d'image.

```yaml .github/workflows/ci.yml theme={null}
name: CI

on:
  push:
    branches: [develop, staging, production]
  pull_request:
    branches: [develop, staging, production]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run linter
        run: npm run lint

      - name: Run tests with coverage
        run: npm run test:coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          files: ./coverage/lcov.info

  security:
    runs-on: ubuntu-latest
    needs: test
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Semgrep SAST
        uses: returntocorp/semgrep-action@v1
        with:
          config: >-
            p/security-audit
            p/owasp-top-ten

      - name: gitleaks (secrets detection)
        uses: zricethezav/gitleaks-action@v2
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

  build:
    runs-on: ubuntu-latest
    needs: [test, security]
    permissions:
      contents: read
      packages: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GHCR_PAT }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=sha,prefix=,suffix=,format=short
            type=semver,pattern={{version}},enable=${{ github.ref == 'refs/heads/production' }}
            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/production' }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max
```

## Étapes standard détaillées

**1. Checkout du code**

Récupération du code source avec `actions/checkout@v4` et historique complet pour les analyses de sécurité.

**2. Setup du runtime**

Installation de Node.js 20 (ou Python 3.11 / Rust selon le projet) avec cache des dépendances.

**3. Installation des dépendances**

`npm ci` pour une installation reproductible et rapide, ou équivalent `pip install` / `cargo build`.

**4. Tests et couverture**

Exécution des tests unitaires et génération du rapport de couverture. Échec de la pipeline si couverture \< 70%.

**5. SAST avec Semgrep**

Analyse statique de sécurité avec les règles OWASP Top 10 et security-audit. Les findings bloquants arrêtent la pipeline.

**6. Détection de secrets avec gitleaks**

Scan du dépôt à la recherche de secrets exposés (clés API, tokens, mots de passe). Zero tolérance.

**7. Build de l'image Docker**

Construction multi-stage avec Buildx et cache GitHub Actions pour accélérer les builds successifs.

**8. Push vers ghcr.io**

Publication de l'image avec le tag approprié : SHA court pour `develop`/`staging`, SemVer pour `production`.

## Stratégie de taggage des images

| Branche | Format du tag | Exemple |
| - | - | - |
| `develop` | SHA court (7 caractères) | `a1b2c3d` |
| `staging` | SHA court (7 caractères) | `a1b2c3d` |
| `production` | SemVer + `latest` | `v2.1.0`, `latest` |

> [!NOTE]
>
> Les secrets utilisés par les workflows (GHCR\_PAT, tokens d'accès) sont stockés dans **GitHub Secrets** au niveau de l'organisation ou du dépôt. Consultez la page dédiée aux secrets pour la procédure de rotation.

> [!WARNING]
>
> La pipeline échoue immédiatement si Semgrep détecte une vulnérabilité de niveau `ERROR` ou si gitleaks trouve un secret exposé. Aucune image n'est publiée en cas d'échec de la phase security.

## Adaptations par langage

**Node.js**

Utilisez `actions/setup-node@v4` avec cache npm. Les étapes de test utilisent `npm test` ou `npm run test:coverage`.

**Python**

Remplacez par `actions/setup-python@v5` et utilisez `pytest` pour les tests. Le build Docker utilise un `requirements.txt` ou `poetry.lock`.

**Rust**

Utilisez `dtolnay/rust-action@stable` pour le toolchain Rust. Les tests utilisent `cargo test` et le build Docker est multi-stage avec `rust:alpine`.

Pour toute modification du workflow standard, ouvrez une PR sur le dépôt de référence et demandez une review à l'équipe DevOps.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.