CLI dan deployment konfigurasi

CLI membuat, memvalidasi, melakukan deployment, mempromosikan, dan melakukan rollback versi konfigurasi ChattyBox yang immutable. Token deployment dibatasi untuk satu project dan environment yang dipilih, sehingga alur kerja yang sama cocok untuk pengembangan lokal dan CI.

Membuat konfigurasi

bunx @openstaticfish/chattybox-cli init

Perintah ini membuat chattybox.config.json:

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

Gunakan path khusus jika konfigurasi berada dalam subdirektori:

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

Memvalidasi secara lokal atau di CI

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

Validasi memeriksa skema, nama asisten yang wajib, tipe sumber yang didukung, URL sumber HTTP, batas halaman positif, dan warna widget. Validasi yang berhasil tidak melakukan deployment atau mengubah state jarak jauh.

Membuat token deployment

Buka tab Settings project, cari Config deployment tokens, lalu buat token untuk environment yang dapat diubah oleh alur kerja Anda. Segera salin token tersebut; ChattyBox hanya menyimpan hash-nya dan tidak dapat menampilkannya lagi.

Atur token dan URL API widget dari tab Embed project:

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

Jangan pernah commit token. Simpan token di secret store terenkripsi milik penyedia CI Anda.

Setelah memverifikasi alur deployment, aktifkan Config-as-code lock di bagian pengaturan yang sama. Lock ini menonaktifkan perubahan konfigurasi dan corpus dari dashboard, sehingga hanya token deployment dengan cakupan yang sesuai yang dapat mengubah runtime. Pembuatan dan pencabutan token tetap tersedia jika kredensial CI perlu dirotasi.

Deploy konfigurasi

Deployment membuat versi immutable dan mempromosikannya ke environment yang dipilih:

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

Promosi development dan preview dicatat untuk ditinjau. Promosi production menerapkan secara atomik prompt asisten, respons fallback, pengaturan widget, locale, dan sumber situs web ke project live. Konfigurasi production harus berisi tepat satu sumber website. Deployment mengantrekan scraping yang terikat pada versi untuk dijalankan setelah job-job sebelumnya selesai. Setelah itu, deployment mengganti corpus lama dan membuat ulang embedding. Runtime saat ini menolak konfigurasi dengan banyak sumber.

Gunakan --json dalam otomatisasi untuk menerima versi, environment, status aplikasi, dan ID job scraping sebagai output terstruktur.

Status, promosi, dan 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

Rollback mempromosikan dan menerapkan ulang versi immutable yang lebih lama; tindakan ini tidak pernah menulis ulang riwayat deployment. Konfigurasi dipulihkan segera, sementara refresh konten yang diperlukan berlanjut secara asinkron.

Workflow CI/CD

Tambahkan CHATTYBOX_DEPLOY_TOKEN sebagai secret terenkripsi yang dicakup untuk production di penyedia CI Anda. Tambahkan CHATTYBOX_API_URL sebagai secret atau variabel menggunakan URL API widget dari tab Embed project. Jalankan validasi pada pull request, tetapi batasi deployment production ke branch default yang dilindungi atau environment deployment yang disetujui.

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

Gunakan secret production yang dicakup oleh environment dan wajibkan persetujuan deployment jika repositori Anda mendukungnya. CLI mencatat variabel commit dan branch CI umum bersama versi immutable.

GitLab CI/CD

Simpan kedua nilai di Settings → CI/CD → Variables. Lindungi token deployment, mask token tersebut, dan cakup ke environment 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 secara otomatis mengekspos CHATTYBOX_DEPLOY_TOKEN dan CHATTYBOX_API_URL ke job menggunakan nama variabelnya. Gunakan branch default yang dilindungi agar variabel yang dilindungi tidak tersedia untuk branch yang tidak tepercaya.

Bitbucket Pipelines

Tambahkan kedua nilai sebagai variabel deployment di Repository settings → Pipelines → Deployments → Production. Tandai token deployment sebagai secured.

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

Ganti main jika branch default Anda memiliki nama lain. Bitbucket hanya menyuntikkan variabel deployment ke langkah yang terkait dengan environment deployment tersebut.

Bagian konfigurasi

Bagian	Tujuan
schemaVersion	Memilih kontrak konfigurasi publik. Versi 1 saat ini didukung.
assistant	Memberi nama asisten dan secara opsional menentukan profil prompt serta prompt sistemnya.
knowledge.sources	Mendeklarasikan sumber situs web serta pola penyertaan dan pengecualian opsional.
runtime	Menyimpan nilai default runtime seperti locale.
widget	Menjelaskan pengaturan presentasi opsional untuk widget yang dihosting.

Helper konfigurasi bertipe

Instal paket konfigurasi saat membangun tooling TypeScript terpisah di sekitar skema:

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 itu sendiri membaca file JSON. defineConfig() ditujukan untuk aplikasi bertipe atau tooling build; fungsi ini tidak membuat file TypeScript dapat langsung dimuat oleh CLI.

Untuk integrasi produksi yang berfungsi saat ini, gunakan widget yang dihosting atau bangun antarmuka khusus dengan SDK JavaScript.