CLI e distribuzione della configurazione

La CLI crea, convalida, distribuisce, promuove ed esegue il rollback di versioni immutabili della configurazione ChattyBox. I token di deployment sono limitati a un singolo progetto e agli ambienti selezionati, quindi lo stesso flusso è adatto allo sviluppo locale e alla CI.

Creare una configurazione

bunx @openstaticfish/chattybox-cli init

Questo comando crea chattybox.config.json:

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

Utilizza un percorso personalizzato quando la configurazione deve trovarsi in una sottodirectory:

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

Convalidare in locale o nella CI

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

La convalida verifica lo schema, il nome obbligatorio dell'assistente, i tipi di fonti supportati, gli URL HTTP delle fonti, i limiti di pagina positivi e i colori del widget. Una convalida riuscita non esegue il deployment e non modifica lo stato remoto.

Creare un token di deployment

Apri la scheda Settings del progetto, cerca Config deployment tokens e crea un token per gli ambienti che il tuo flusso di lavoro può modificare. Copialo subito: ChattyBox memorizza solo il suo hash e non può mostrarlo nuovamente.

Imposta il token e l'URL API del widget dalla scheda Embed del progetto:

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

Non eseguire mai il commit del token. Conservalo nel gestore di secret crittografati del tuo provider CI.

Dopo aver verificato il flusso di deployment, abilita Config-as-code lock nella stessa sezione delle impostazioni. Il blocco disabilita le modifiche alla configurazione e al corpus dalla dashboard, così solo i token di deployment con l’ambito corretto possono modificare il runtime. La creazione e la revoca dei token restano disponibili se è necessario ruotare una credenziale CI.

Distribuire la configurazione

Il deployment crea una versione immutabile e la promuove nell'ambiente selezionato:

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

Le promozioni a development e preview vengono registrate per la revisione. Le promozioni a production applicano atomicamente al progetto live il prompt dell'assistente, la risposta di fallback, le impostazioni del widget, le impostazioni locali e la fonte del sito web. La configurazione di produzione deve contenere esattamente una fonte del sito web. Un deployment accoda uno scraping associato alla versione, che viene eseguito dopo il completamento dei job precedenti. Poi il deployment sostituisce il corpus precedente e rigenera gli embedding. Il runtime attuale rifiuta le configurazioni con più fonti.

Usa --json nelle automazioni per ricevere versione, ambiente, stato dell'applicazione e ID del job di scraping in un output strutturato.

Stato, promozione e rollback

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

Il rollback promuove e riapplica una versione immutabile precedente; non riscrive mai la cronologia dei deployment. Ripristina immediatamente la configurazione, mentre ogni aggiornamento dei contenuti necessario continua in modo asincrono.

Workflow CI/CD

Aggiungi CHATTYBOX_DEPLOY_TOKEN come secret crittografato con ambito production nel tuo provider CI. Aggiungi CHATTYBOX_API_URL come secret o variabile usando l'URL API del widget dalla scheda Embed del progetto. Esegui la validazione sulle pull request, ma limita il deployment in produzione al branch predefinito protetto o a un ambiente di deployment approvato.

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

Usa un secret di produzione con ambito limitato all'ambiente e richiedi l'approvazione del deployment quando il tuo repository lo supporta. La CLI registra le variabili CI comuni relative al commit e al branch insieme alla versione immutabile.

GitLab CI/CD

Archivia entrambi i valori in Settings → CI/CD → Variables. Proteggi il token di deployment, mascheralo e limita il suo ambito all'ambiente 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 espone automaticamente al job CHATTYBOX_DEPLOY_TOKEN e CHATTYBOX_API_URL usando i rispettivi nomi di variabile. Usa un branch predefinito protetto, in modo che le variabili protette non siano disponibili per branch non attendibili.

Bitbucket Pipelines

Aggiungi entrambi i valori come variabili di deployment in Repository settings → Pipelines → Deployments → Production. Contrassegna il token di deployment come protetto.

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

Sostituisci main se il tuo branch predefinito ha un altro nome. Bitbucket inserisce le variabili di deployment solo nei passaggi associati a quell'ambiente di deployment.

Sezioni di configurazione

Sezione	Scopo
schemaVersion	Seleziona il contratto pubblico di configurazione. Attualmente è supportata la versione 1.
assistant	Assegna un nome all'assistente e, facoltativamente, ne definisce il profilo delle istruzioni e l'istruzione di sistema.
knowledge.sources	Dichiara le fonti dei siti web ed eventuali pattern di inclusione o esclusione.
runtime	Contiene i valori predefiniti di runtime, come le impostazioni locali.
widget	Descrive le impostazioni facoltative di presentazione del widget ospitato.

Funzione di supporto per la configurazione tipizzata

Installa il pacchetto di configurazione se crei strumenti TypeScript separati basati sullo schema:

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 legge direttamente file JSON. defineConfig() è destinata ad applicazioni tipizzate o strumenti di build; non rende i file TypeScript direttamente caricabili dalla CLI.

Per un'integrazione funzionante in produzione oggi, utilizza il widget ospitato oppure crea un'interfaccia personalizzata con l'SDK JavaScript.