CLI et déploiement de configuration

La CLI crée, valide, déploie, promeut et restaure des versions immuables de la configuration ChattyBox. Les jetons de déploiement sont limités à un projet et aux environnements sélectionnés, ce qui rend le même flux adapté au développement local et à la CI.

Créer une configuration

bunx @openstaticfish/chattybox-cli init

Cette commande crée chattybox.config.json :

{
  "schemaVersion": "1",
  "assistant": {
    "name": "Support"
  },
  "knowledge": {
    "sources": [
      {
        "type": "website",
        "url": "https://example.com"
      }
    ]
  },
  "widget": {
    "enabled": true
  }
}

Utilisez un chemin personnalisé lorsque la configuration doit se trouver dans un sous-répertoire :

bunx @openstaticfish/chattybox-cli init config/chattybox.config.json

Valider localement ou dans la CI

bunx @openstaticfish/chattybox-cli validate
bunx @openstaticfish/chattybox-cli validate config/chattybox.config.json

La validation vérifie le schéma, le nom obligatoire de l'assistant, les types de sources pris en charge, les URL HTTP des sources, les limites de pages positives et les couleurs du widget. Une validation réussie ne déploie ni ne modifie aucun état distant.

Créer un jeton de déploiement

Ouvrez l'onglet Settings du projet, recherchez Config deployment tokens et créez un jeton pour les environnements que votre flux de travail peut modifier. Copiez-le immédiatement ; ChattyBox ne stocke que son hash et ne peut plus l'afficher.

Définissez le jeton et l'URL d'API du widget depuis l'onglet Embed du projet :

export CHATTYBOX_DEPLOY_TOKEN='cb_cfg_v1_...'
export CHATTYBOX_API_URL='https://your-deployment.convex.site/chat'

Ne commitez jamais le jeton. Stockez-le dans le gestionnaire de secrets chiffrés de votre fournisseur CI.

Après avoir vérifié le flux de déploiement, activez Config-as-code lock dans la même section des paramètres. Le verrou désactive les modifications de configuration et du corpus depuis le tableau de bord, de sorte que seuls les jetons de déploiement avec la portée appropriée puissent modifier le runtime. La création et la révocation des jetons restent disponibles si un identifiant CI doit faire l’objet d’une rotation.

Déployer la configuration

Le déploiement crée une version immuable et la promeut dans l'environnement sélectionné :

bunx @openstaticfish/chattybox-cli deploy --environment preview
bunx @openstaticfish/chattybox-cli deploy --environment production

Les promotions vers development et preview sont enregistrées pour examen. Les promotions vers production appliquent atomiquement le prompt de l'assistant, la réponse de secours, les paramètres du widget, la locale et la source du site au projet en production. La configuration de production doit contenir exactement une source de site web. Un déploiement met en file d’attente un scraping lié à la version, qui s’exécute après la fin des jobs précédents. Il remplace ensuite l’ancien corpus et régénère les embeddings. Le runtime actuel rejette les configurations comportant plusieurs sources.

Utilisez --json dans les automatisations pour recevoir la version, l'environnement, l'état de l'application et l'ID du job de scraping sous forme structurée.

État, promotion et restauration

bunx @openstaticfish/chattybox-cli status --environment production

bunx @openstaticfish/chattybox-cli promote \
  --version '<config-version-id>' \
  --environment production

bunx @openstaticfish/chattybox-cli rollback \
  --version '<known-good-config-version-id>' \
  --environment production

La restauration promeut et réapplique une version immuable antérieure ; elle ne réécrit jamais l'historique des déploiements. Elle restaure immédiatement la configuration, tandis que toute actualisation nécessaire du contenu se poursuit de manière asynchrone.

Workflows CI/CD

Ajoutez CHATTYBOX_DEPLOY_TOKEN en tant que secret chiffré limité à la production chez votre fournisseur CI. Ajoutez CHATTYBOX_API_URL comme secret ou variable en utilisant l'URL d'API du widget de l'onglet Embed du projet. Exécutez la validation sur les pull requests, mais limitez le déploiement en production à votre branche par défaut protégée ou à un environnement de déploiement approuvé.

GitHub Actions

name: Deploy ChattyBox configuration

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bunx @openstaticfish/chattybox-cli validate

  deploy:
    if: github.event_name == 'push'
    needs: validate
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - name: Validate and deploy
        env:
          CHATTYBOX_DEPLOY_TOKEN: ${{ secrets.CHATTYBOX_DEPLOY_TOKEN }}
          CHATTYBOX_API_URL: ${{ vars.CHATTYBOX_API_URL }}
        run: |
          bunx @openstaticfish/chattybox-cli validate
          bunx @openstaticfish/chattybox-cli deploy --environment production --json

Utilisez un secret de production limité à l'environnement et exigez une approbation de déploiement lorsque votre dépôt le permet. La CLI enregistre les variables CI courantes du commit et de la branche avec la version immuable.

GitLab CI/CD

Stockez les deux valeurs sous Settings → CI/CD → Variables. Protégez le token de déploiement, masquez-le et limitez sa portée à l'environnement production.

.gitlab-ci.yml

image: oven/bun:1

validate_chattybox:
  stage: test
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  script:
    - bunx @openstaticfish/chattybox-cli validate

deploy_chattybox:
  stage: deploy
  environment: production
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - bunx @openstaticfish/chattybox-cli validate
    - bunx @openstaticfish/chattybox-cli deploy --environment production --json

GitLab expose automatiquement CHATTYBOX_DEPLOY_TOKEN et CHATTYBOX_API_URL au job en utilisant leurs noms de variables. Utilisez une branche par défaut protégée afin que les variables protégées ne soient pas disponibles pour les branches non fiables.

Bitbucket Pipelines

Ajoutez les deux valeurs en tant que variables de déploiement sous Repository settings → Pipelines → Deployments → Production. Marquez le token de déploiement comme sécurisé.

bitbucket-pipelines.yml

image: oven/bun:1

pipelines:
  pull-requests:
    '**':
      - step:
          name: Validate ChattyBox configuration
          script:
            - bunx @openstaticfish/chattybox-cli validate
  branches:
    main:
      - step:
          name: Deploy ChattyBox configuration
          deployment: Production
          script:
            - bunx @openstaticfish/chattybox-cli validate
            - bunx @openstaticfish/chattybox-cli deploy --environment production --json

Remplacez main si votre branche par défaut porte un autre nom. Bitbucket injecte les variables de déploiement uniquement dans les étapes associées à cet environnement de déploiement.

Sections de configuration

Section	Objectif
schemaVersion	Sélectionne le contrat de configuration public. La version 1 est actuellement prise en charge.
assistant	Nomme l'assistant et définit facultativement son profil de prompt et son prompt système.
knowledge.sources	Déclare les sources de sites web et les modèles facultatifs d'inclusion ou d'exclusion.
runtime	Contient les valeurs par défaut d'exécution, telles que la locale.
widget	Décrit les paramètres de présentation facultatifs du widget hébergé.

Utilitaire de configuration typé

Installez le package de configuration pour créer des outils TypeScript distincts autour du schéma :

bun add -d @openstaticfish/chattybox-config

import { defineConfig } from '@openstaticfish/chattybox-config';

const config = defineConfig({
  schemaVersion: '1',
  assistant: { name: 'Support' },
  knowledge: {
    sources: [{ type: 'website', url: 'https://docs.example.com' }],
  },
  widget: { enabled: true },
});

La CLI elle-même lit des fichiers JSON. defineConfig() est destiné aux applications typées ou aux outils de build ; il ne permet pas à la CLI de charger directement des fichiers TypeScript.

Pour une intégration fonctionnelle en production dès aujourd'hui, utilisez le widget hébergé ou créez une interface personnalisée avec le SDK JavaScript.