CLI och konfigurationsdistribution

CLI:t skapar, validerar, distribuerar, promoterar och återställer oföränderliga ChattyBox-konfigurationsversioner. Distributionstoken begränsas till ett projekt och valda miljöer, vilket gör samma arbetsflöde lämpligt för lokal utveckling och CI.

Skapa en konfiguration

bunx @openstaticfish/chattybox-cli init

Detta skapar chattybox.config.json:

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

Använd en anpassad sökväg när konfigurationen hör hemma i en underkatalog:

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

Validera lokalt eller i CI

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

Valideringen kontrollerar schemat, det obligatoriska assistentnamnet, stödda källtyper, HTTP-URL:er för källor, positiva sidgränser och widgetfärger. En godkänd validering distribuerar eller ändrar inte fjärrtillståndet.

Skapa en distributionstoken

Öppna projektets flik Settings, leta reda på Config deployment tokens och skapa en token för de miljöer som arbetsflödet kan ändra. Kopiera den direkt; ChattyBox lagrar bara dess hash och kan inte visa den igen.

Ange token och widgetens API-URL från projektets flik Embed:

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

Checka aldrig in token. Lagra den i CI-leverantörens krypterade hemlighetslager.

När du har verifierat distributionsarbetsflödet aktiverar du Config-as-code lock i samma inställningssektion. Låset inaktiverar konfigurations- och korpusändringar från kontrollpanelen, så att endast distributionstoken med rätt begränsning kan ändra runtime-miljön. Det går fortfarande att skapa och återkalla token om en CI-autentiseringsuppgift behöver roteras.

Distribuera konfigurationen

En distribution skapar en oföränderlig version och promoterar den till den valda miljön:

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

Promoteringar till utvecklings- och förhandsgranskningsmiljöer registreras för granskning. Produktionspromoteringar tillämpar atomiskt assistentens prompt, reservsvaret, widgetinställningarna, lokalinställningen och webbplatskällan på det aktiva projektet. Produktionskonfigurationen måste innehålla exakt en webbplatskälla. En distribution lägger ett versionsbundet skrapningsjobb i kö som körs efter att tidigare jobb har slutförts. Därefter ersätter distributionen den tidigare korpusen och genererar embeddingar på nytt. Den aktuella runtime-miljön avvisar konfigurationer med flera källor.

Använd --json i automatisering för att få versionen, miljön, applikationsstatusen och ID:t för skrapningsjobbet som strukturerad utdata.

Status, promotering och återställning

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

En återställning promoterar och tillämpar en äldre oföränderlig version på nytt; den skriver aldrig om distributionshistoriken. Den återställer konfigurationen omedelbart, medan eventuell nödvändig innehållsuppdatering fortsätter asynkront.

CI/CD-arbetsflöden

Lägg till CHATTYBOX_DEPLOY_TOKEN som en krypterad produktionsbegränsad hemlighet hos din CI-leverantör. Lägg till CHATTYBOX_API_URL som en hemlighet eller variabel med widgetens API-URL från projektets Embed-flik. Kör validering på pull requests, men begränsa produktionsdistribution till din skyddade standardgren eller en godkänd distributionsmiljö.

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

Använd en produktionshemlighet som är begränsad till miljön och kräv godkännande av distributionen när ditt arkiv stöder det. CLI:t registrerar vanliga CI-variabler för commit och branch tillsammans med den oföränderliga versionen.

GitLab CI/CD

Lagra båda värdena under Settings → CI/CD → Variables. Skydda distributionstoken, maskera den och begränsa den till miljön 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 exponerar automatiskt CHATTYBOX_DEPLOY_TOKEN och CHATTYBOX_API_URL för jobbet med deras variabelnamn. Använd en skyddad standardgren så att skyddade variabler inte är tillgängliga för opålitliga grenar.

Bitbucket Pipelines

Lägg till båda värdena som distributionsvariabler under Repository settings → Pipelines → Deployments → Production. Markera distributionstoken som säkrad.

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

Ersätt main om din standardgren har ett annat namn. Bitbucket injicerar distributionsvariabler endast i steg som är kopplade till den distributionsmiljön.

Konfigurationsavsnitt

Avsnitt	Syfte
schemaVersion	Väljer det offentliga konfigurationskontraktet. Version 1 stöds för närvarande.
assistant	Namnger assistenten och definierar valfritt dess promptprofil och systemprompt.
knowledge.sources	Deklarerar webbplatskällor och valfria mönster för inkludering och exkludering.
runtime	Innehåller standardvärden för körning, till exempel språkversion.
widget	Beskriver valfria presentationsinställningar för den hostade widgeten.

Typad konfigurationshjälp

Installera konfigurationspaketet när du bygger separata TypeScript-verktyg kring schemat:

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

CLI:n läser själv JSON-filer. defineConfig() är avsedd för typade program eller byggverktyg; den gör inte TypeScript-filer direkt läsbara för CLI:n.

För en fungerande produktionsintegration i dag kan du använda den hostade widgeten eller bygga ett anpassat gränssnitt med JavaScript SDK.