PostgreSQL: GitHub Actions & GitLab CI

Lancez un véritable service PostgreSQL depuis votre pipeline GitHub Actions ou GitLab CI, exécutez vos tests dessus, puis supprimez-le automatiquement

👋 Bienvenue sur la documentation de Stackhero !

Stackhero propose une solution PostgreSQL cloud prête à l'emploi qui offre de nombreux avantages, notamment :

Connexions et transferts de données illimités.

Interface web PgAdmin incluse.

De nombreux modules inclus comme PostGIS, TimescaleDB et PgVector.

Mises à jour simplifiées en un clic.

Performance optimale et sécurité renforcée grâce à une VM privée et dédiée.

Gagnez du temps et simplifiez-vous la vie : il suffit de 5 minutes pour essayer la solution PostgreSQL cloud hosting de Stackhero !

Ce guide vous explique comment exécuter un service PostgreSQL réel et dédié dans votre pipeline CI avec GitHub Actions ou GitLab CI. En suivant ces étapes, vous pouvez tester votre code sur une instance PostgreSQL active dans des conditions proches de la production, sans avoir à utiliser de mocks ou de simulations. PostgreSQL is a powerful, open source object-relational SQL database that your app can rely on in production.

À chaque exécution de votre pipeline, une nouvelle instance PostgreSQL est créée. Vos tests interagissent donc avec le même type de service que vos utilisateurs en production. Le workflow crée automatiquement une stack temporaire, ajoute PostgreSQL, attend qu'il soit prêt, récupère les identifiants générés, lance un smoke test avec psql, puis nettoie toujours tout à la fin de l'exécution.

Vous utiliserez le Stackhero CLI, un outil en ligne de commande autonome qui permet de lancer et gérer des services Stackhero de façon simple et rapide.

1. Créez un access token et stockez-le comme secret CI

Pour permettre au CLI de fonctionner sans interaction, vous aurez besoin d'un access token (format : usr-xxxxxx:tokenId). Il suffit de créer ce token une seule fois, puis de l'ajouter à votre pipeline CI comme secret sécurisé et chiffré.

Créez le token : Sur votre tableau de bord Stackhero, cliquez sur votre photo de profil en haut à droite, allez dans Votre compte, puis Access tokens, et cliquez sur Créer un token.
Pour GitHub Actions : Dans votre dépôt, allez dans Settings > Secrets and variables > Actions > New repository secret, et saisissez le token sous le nom STACKHERO_TOKEN.
Pour GitLab CI : Dans votre projet, allez dans Settings > CI/CD > Variables > Add variable, définissez la clé sur STACKHERO_TOKEN, puis cochez Masked (et Protected si votre CI ne s'exécute que sur des branches protégées).

N'ajoutez jamais votre access token directement dans le fichier YAML de votre pipeline. S'il est présent dans le YAML, il pourrait être exposé à toute personne ayant accès au dépôt et apparaître dans les logs de build. Le stocker comme secret CI garantit qu'il reste chiffré et masqué, assurant la sécurité de votre token.

2. Le script de cycle de vie

Voici un exemple complet de script qui gère tout le cycle de vie du service. Il montre à quel point la configuration est simple, avec seulement quelques commandes. Vous pouvez copier le YAML prêt à l'emploi pour votre plateforme dans les sections ci-dessous.

#!/bin/bash
set -euo pipefail

# STACKHERO_TOKEN est fourni par le secret CI, le CLI le détecte automatiquement.

stackName="ci-postgresql-$$"          # Nom de stack unique pour chaque exécution
serviceStore="postgresql"             # Le store du service PostgreSQL
instance="10G"        # Modifiez si besoin (voir étape 3)
region="europe"                         # Nom de la région (voir stackhero regions-list)

# 1. Installer le CLI sur le runner
curl -fsSL https://www.stackhero.io/install.sh | sh

# 2. Installer le client nécessaire pour le smoke test (jq + curl sont la base)
apt-get update && apt-get install -y --no-install-recommends jq curl postgresql-client

# 3. Créer une stack dédiée pour cette exécution
stackId=$(stackhero --format=script stack-create --name="$stackName")
echo "Stack créée : $stackId"

# 4. Ajouter PostgreSQL et récupérer son service id
serviceId=$(stackhero --format=script service-add \
  --stack="$stackId" \
  --service-store="$serviceStore" \
  --instance="$instance" \
  --region="$region")
echo "Service ajouté : $serviceId"

# 5. Attendre que le service soit opérationnel (cela peut prendre quelques minutes)
stackhero service-wait-for --service="$serviceId"

# 6. Lire la configuration (contient les identifiants générés)
config=$(stackhero service-configuration-get --service="$serviceId" --format=json)

# 7. Extraire les identifiants nécessaires
host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.password')

# 8. Smoke test : Run a trivial query against the database.
PGPASSWORD="$password" psql "host=$host port=5432 user=admin dbname=admin sslmode=require" -c "SELECT 1;"

echo "✅ PostgreSQL est accessible depuis la CI."

L'étape de suppression, qui efface le service, attend sa suppression puis supprime la stack, est détaillée dans les sections spécifiques à chaque plateforme ci-dessous. Cette méthode garantit que le nettoyage est toujours effectué, même si un smoke test échoue.

Une stack ne peut être supprimée que si elle est vide. Supprimez toujours le service en premier et attendez sa suppression, puis supprimez la stack. La commande service-wait-for garantit que le service est bien en cours d'exécution ou supprimé avant de continuer, c'est donc l'outil adapté pour attendre la suppression.

3. Choisissez la taille d'instance

Les exemples ci-dessous utilisent par défaut l'instance d'entrée de gamme 10G pour PostgreSQL. C'est un choix fiable pour la plupart des usages, mais vous pouvez l'adapter selon vos besoins. Pour voir toutes les tailles d'instances disponibles pour PostgreSQL, exécutez :

# La colonne NAME indique la valeur à passer à --instance
stackhero instances-store-list --service-store=postgresql

4. GitHub Actions

Pour commencer, enregistrez le contenu suivant dans .github/workflows/ci.yml. Désormais, chaque push et pull request lancera des tests sur une vraie instance PostgreSQL.

name: CI avec PostgreSQL

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      STACKHERO_TOKEN: ${{ secrets.STACKHERO_TOKEN }}
      STACK_NAME: ci-postgresql-${{ github.run_id }}-${{ github.run_attempt }}
      INSTANCE: "10G"   # Modifiez si besoin (voir étape 3)
      REGION: europe
    steps:
      - uses: actions/checkout@v4

      - name: Installer le Stackhero CLI et le client
        run: |
          curl -fsSL https://www.stackhero.io/install.sh | sh
          apt-get update && apt-get install -y --no-install-recommends jq curl postgresql-client

      - name: Créer le service PostgreSQL
        run: |
          set -euo pipefail
          STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
          echo "STACK_ID=$STACK_ID" >> "$GITHUB_ENV"
          SERVICE_ID=$(stackhero --format=script service-add \
            --stack="$STACK_ID" \
            --service-store="postgresql" \
            --instance="$INSTANCE" \
            --region="$REGION")
          echo "SERVICE_ID=$SERVICE_ID" >> "$GITHUB_ENV"
          stackhero service-wait-for --service="$SERVICE_ID"

      - name: Exécuter les tests sur PostgreSQL
        run: |
          set -euo pipefail
          config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
          host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.password')
          # Run a trivial query against the database.
          PGPASSWORD="$password" psql "host=$host port=5432 user=admin dbname=admin sslmode=require" -c "SELECT 1;"
          echo "✅ PostgreSQL est accessible depuis la CI."
          # Vous pouvez lancer votre propre suite de tests ici avec les identifiants ci-dessus ...

      - name: Nettoyage (toujours, même en cas d'échec)
        if: always()
        run: |
          if [ -n "${SERVICE_ID:-}" ]; then
            stackhero service-delete --service="$SERVICE_ID" --confirm
            stackhero service-wait-for --service="$SERVICE_ID"
          fi
          if [ -n "${STACK_ID:-}" ]; then
            stackhero stack-delete --stack="$STACK_ID" --confirm
          fi

L'étape de nettoyage utilise if: always() pour s'assurer qu'elle s'exécute dans tous les cas, garantissant la suppression de votre instance PostgreSQL et évitant toute facturation pour des ressources inutilisées.

5. GitLab CI

Vous pouvez enregistrer cette configuration sous .gitlab-ci.yml. Avec ce setup, chaque pipeline crée une nouvelle instance PostgreSQL pour vos tests.

test:
  image: ubuntu:24.04
  variables:
    STACK_NAME: "ci-postgresql-$CI_PIPELINE_ID-$CI_JOB_ID"
    INSTANCE: "10G"   # Modifiez si besoin (voir étape 3)
    REGION: "europe"
    SERVICE_STORE: "postgresql"
  # STACKHERO_TOKEN provient de la variable CI/CD créée à l'étape 1.
  script:
    - set -euo pipefail
    - curl -fsSL https://www.stackhero.io/install.sh | sh
    - apt-get update && apt-get install -y --no-install-recommends jq curl postgresql-client
    - STACK_ID=$(stackhero --format=script stack-create --name="$STACK_NAME")
    - echo "STACK_ID=$STACK_ID" >> deploy.env
    - SERVICE_ID=$(stackhero --format=script service-add --stack="$STACK_ID" --service-store="$SERVICE_STORE" --instance="$INSTANCE" --region="$REGION")
    - echo "SERVICE_ID=$SERVICE_ID" >> deploy.env
    - stackhero service-wait-for --service="$SERVICE_ID"
    - config=$(stackhero service-configuration-get --service="$SERVICE_ID" --format=json)
    - host=$(echo "$config" | jq -r '.configuration.domain')
password=$(echo "$config" | jq -r '.configuration.password')
    # Run a trivial query against the database.
    - PGPASSWORD="$password" psql "host=$host port=5432 user=admin dbname=admin sslmode=require" -c "SELECT 1;"
    - echo "✅ PostgreSQL est accessible depuis la CI."
    # Vous pouvez lancer votre propre suite de tests ici avec les identifiants ci-dessus ...
  after_script:
    - test -f deploy.env && . ./deploy.env || true
    - >
      if [ -n "${SERVICE_ID:-}" ]; then
        stackhero service-delete --service="$SERVICE_ID" --confirm
        stackhero service-wait-for --service="$SERVICE_ID"
      fi
    - >
      if [ -n "${STACK_ID:-}" ]; then
        stackhero stack-delete --stack="$STACK_ID" --confirm
      fi

Sur GitLab, le nettoyage s'effectue dans after_script. Cette section est toujours exécutée, même si le job échoue, ce qui garantit la suppression de vos ressources PostgreSQL et évite toute facturation inutile.

Sur GitLab, after_script s'exécute dans un shell vierge. Pour gérer cela, le script écrit les IDs du service et de la stack dans deploy.env pendant le job, puis les recharge avant le nettoyage. Ainsi, même en cas d'échec en cours de job, vos ressources sont bien supprimées.

Voilà le cycle CI complet pour PostgreSQL : création d'une stack, ajout du service, attente, récupération des identifiants, smoke test, et nettoyage systématique. Chaque exécution de pipeline bénéficie d'un service réel et isolé, sans rien laisser tourner après coup. Pour plus d'informations sur les commandes disponibles et l'authentification non interactive avec STACKHERO_TOKEN, vous pouvez consulter la documentation CLI complète.