CLI en configuratiedeployment

De gepubliceerde CLI/config-artefacten van versie 0.3.1 implementeren het configuratie-/backendcontract 0.3.0 en weigeren onbekende sleutels zowel lokaal als in de backend.

De CLI maakt, valideert, deployt, promoot en rolt onveranderlijke ChattyBox-configuratieversies terug. Deploymenttokens zijn beperkt tot één project en geselecteerde omgevingen, waardoor dezelfde workflow geschikt is voor lokale ontwikkeling en CI.

Publicatie- en runtimestatus

In het openbare register zijn @openstaticfish/chattybox-cli@0.3.1, @openstaticfish/chattybox-config@0.3.1 en de afzonderlijke JavaScript-SDK @openstaticfish/chattybox@0.1.4 gepubliceerd. Deze artefacten ondersteunen de uitgebreide velden samen met het backendcontract 0.3.0. status toont de omgevingsversie, terwijl runtimeConfigVersionId de laatst op de gedeelde runtime toegepaste configuratie aanduidt en kan verschillen. Een weggelaten mode kiest crawl en behoudt een expliciete maxDepth: 0. De ESM-CLI vereist Node 20+; kies Bun zo nodig expliciet met bunx --bun.

Een configuratie maken

bunx @openstaticfish/chattybox-cli init

Hiermee wordt chattybox.config.json gemaakt:

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

Gebruik een aangepast pad wanneer de configuratie in een submap thuishoort:

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

Lokaal of in CI valideren

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

De validatie controleert het schema, de verplichte assistentnaam, ondersteunde brontypen, HTTP-URL's van bronnen, positieve paginalimieten en widgetkleuren. Een geslaagde validatie voert geen deployment uit en wijzigt geen externe status.

Een deploymenttoken maken

Open in het project het tabblad Settings, zoek Config deployment tokens en maak een token aan voor de omgevingen die je workflow mag wijzigen. Kopieer het meteen; ChattyBox slaat alleen de hash op en kan het niet opnieuw tonen.

Stel het token en de widget-API-URL in vanuit het tabblad Embed van het project:

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

Commit het token nooit. Bewaar het in de versleutelde secretopslag van je CI-provider.

Schakel na controle van de workflow eventueel Config-as-code lock in. Deze vergrendeling is onomkeerbaar in het huidige dashboard, CLI en API. Ze blokkeert dashboardconfiguratie en handmatige corpusacties (scrapen, verwijderen, rebuild), maar niet gepland werk, projectverwijdering, openbare sleutels of tokens. Branding is de uitzondering: de brandinginstelling blijft afhankelijk van het abonnement wijzigbaar in het dashboard.

Configuratie deployen

Een deployment maakt een onveranderlijke versie en promoot deze naar de geselecteerde omgeving:

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

development legt alleen versie en pointer vast, zonder runtime toe te passen. preview en production delen dezelfde runtime, hetzelfde corpus en dezelfde openbare sleutels: de laatste runtimepromotie wint, zonder omgevingsisolatie. Gebruik afzonderlijke projecten en tokens voor echte scheiding. Een runtimepromotie past configuratie toe en zet een scrape in de wachtrij, maar wacht niet op scraping of embeddings; weggelaten oude URL’s worden niet verwijderd en het corpus is geen versie-snapshot.

Gebruik --json in automatisering om de versie, omgeving, applicatiestatus en ID van de scrapetaak als gestructureerde uitvoer te ontvangen.

Status, promotie en 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

--version verwacht de ondoorzichtige configuratieversie-ID, niet het zichtbare nummer. Rollback gebruikt dezelfde backendbewerking als promote, hoeft geen oudere versie te kiezen en overschrijft de pointer en promotiemetadata van de geselecteerde omgeving; er is geen append-only promotiegeschiedenis. Voor preview of production past rollback de configuratie opnieuw toe met de huidige rechten en zet het een nieuwe vernieuwing in de wachtrij, in plaats van historische inhoud te herstellen.

CI/CD-workflows

Voeg CHATTYBOX_DEPLOY_TOKEN toe als een versleuteld geheim met productiescope bij je CI-provider. Voeg CHATTYBOX_API_URL toe als geheim of variabele met de widget-API-URL uit het tabblad Embed van het project. Voer validatie uit voor pull requests, maar beperk productie-deployments tot je beveiligde standaardbranch of een goedgekeurde deploymentomgeving.

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
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - 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
      - uses: actions/setup-node@v6
        with:
          node-version: 24
      - 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

Gebruik een productiegeheim dat aan de omgeving is gebonden en vereist deploymentgoedkeuring wanneer je repository dit ondersteunt. De CLI legt veelgebruikte CI-commit- en branchvariabelen vast bij de onveranderlijke versie.

GitLab CI/CD

Sla beide waarden op onder Settings → CI/CD → Variables. Bescherm het deploymenttoken, maskeer het en beperk het tot de omgeving production.

.gitlab-ci.yml

image: oven/bun:1

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

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

GitLab stelt CHATTYBOX_DEPLOY_TOKEN en CHATTYBOX_API_URL automatisch beschikbaar aan de job met hun variabelenamen. Gebruik een beveiligde standaardbranch, zodat beschermde variabelen niet beschikbaar zijn voor onbetrouwbare branches.

Bitbucket Pipelines

Voeg beide waarden als deploymentvariabelen toe onder Repository settings → Pipelines → Deployments → Production. Markeer het deploymenttoken als beveiligd.

bitbucket-pipelines.yml

image: oven/bun:1

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

Vervang main als je standaardbranch een andere naam heeft. Bitbucket injecteert deploymentvariabelen alleen in stappen die aan die deploymentomgeving zijn gekoppeld.

Configuratiesecties

Sectie	Doel
schemaVersion	Selecteert het openbare configuratiecontract. Versie 1 wordt momenteel ondersteund.
assistant	Geeft de assistent een naam en definieert optioneel het instructieprofiel en de systeeminstructie.
knowledge.sources	Declareert websitebronnen en optionele patronen voor opnemen of uitsluiten.
runtime	Bevat standaardwaarden voor de runtime, zoals de locale.
widget	Beschrijft optionele presentatie-instellingen voor de gehoste widget.

Helper voor getypeerde configuratie

Installeer het configuratiepakket wanneer je afzonderlijke TypeScript-tooling rond het schema bouwt:

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 },
});

De CLI zelf leest JSON-bestanden. defineConfig() is bedoeld voor getypeerde applicatie- of buildtooling; TypeScript-bestanden worden hierdoor niet rechtstreeks laadbaar voor de CLI.

Gebruik voor een werkende productie-integratie op dit moment de gehoste widget of bouw een aangepaste interface met de JavaScript-SDK.