CLI en configuratiedeployment

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.

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 nadat je de deploymentworkflow hebt gecontroleerd Config-as-code lock in dezelfde instellingensectie in. De vergrendeling schakelt configuratiewijzigingen en corpusmutaties vanuit het dashboard uit, zodat alleen deploymenttokens met de juiste scope de runtime kunnen wijzigen. Het aanmaken en intrekken van tokens blijft mogelijk als een CI-credential moet worden geroteerd.

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

Promoties naar development en preview worden vastgelegd voor beoordeling. Promoties naar production passen de assistentprompt, fallbackreactie, widgetinstellingen, locale en websitebron atomair toe op het liveproject. De productieconfiguratie moet precies één websitebron bevatten. Een deployment zet een aan de versie gekoppelde scrape in de wachtrij, die wordt uitgevoerd nadat eerdere taken zijn afgerond. Daarna wordt het vorige corpus vervangen en worden de embeddings opnieuw gegenereerd. De huidige runtime weigert configuraties met meerdere bronnen.

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

Een rollback promoot een oudere onveranderlijke versie en past deze opnieuw toe; de deploymentgeschiedenis wordt nooit herschreven. De configuratie wordt onmiddellijk hersteld, terwijl elke vereiste inhoudsvernieuwing asynchroon doorgaat.

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
      - 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

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 @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 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 @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

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.