CircleCI Integration

Send your documentation to your chatbot on every build

Overview

Your documentation lives in a Git repository. Your chatbot answers from the Asyntai knowledge base. The Asyntai knowledge sync orb keeps the two the same.

Merge a change to a page, and the chatbot answers from the new page in the same build. Your writers keep their normal workflow, and your visitors get the current answer.

How It Works

The orb adds one step to a pipeline. The step reads the files you point it at, compares them with your knowledge base, and sends what changed.

A new file becomes a new knowledge base entry.
A changed file replaces its entry.
A file with the same text is left alone, so a run costs nothing against your daily limit.
With prune on, an entry whose file is gone is removed.

The entry title is the file path, so you can find every page in Knowledge Base in your dashboard. Each run ends with a line that counts what it did.

Requirements

A CircleCI project
An Asyntai account on the Starter plan or higher, because the orb uses the Asyntai API

Installation

Follow these steps to add the orb to your pipeline:

Get Your API Key

Add an Environment Variable

In CircleCI, open Project Settings → Environment Variables, press Add Environment Variable, and name it ASYNTAI_API_KEY. Paste your key as the value.

Add the Job

Open .circleci/config.yml and add the orb and the job:

version: 2.1

orbs:
  asyntai: asyntai/[email protected]

workflows:
  publish-docs:
    jobs:
      - asyntai/sync:
          path: docs
          filters:
            branches:
              only: main

Push and Watch

Push the change. Open the pipeline in CircleCI and open the Send documentation to Asyntai step. The last line counts how many entries the run added, updated, or left alone.

Settings

Parameter	Default	What it does
`path`	required	The file or folder to read.
`patterns`	`.md,.mdx,*.txt`	Comma separated file patterns to include.
`exclude`	empty	Comma separated patterns to skip, for example `drafts/*`.
`title-prefix`	empty	Text put in front of every entry title. Use it when several repositories feed one chatbot.
`website-id`	empty	Which website to fill. Empty means the first website of the account.
`api-key-var`	`ASYNTAI_API_KEY`	The environment variable that holds your key.
`prune`	`false`	Delete entries whose file is gone. Needs `title-prefix`.
`dry-run`	`false`	List the files and send nothing.

A Step Inside Your Own Job

Use the asyntai/sync command when you want the step after a job that builds your documentation. Run it in an image that holds Python 3.

jobs:
  build-docs:
    docker:
      - image: cimg/python:3.12
    steps:
      - checkout
      - run: make html
      - asyntai/sync:
          path: build/html
          patterns: "*.html"

Several Repositories, One Chatbot

Give each repository its own title-prefix, for example product-docs/ and handbook/. Then turn prune on. Each pipeline only touches the entries that carry its own prefix.

      - asyntai/sync:
          path: docs
          title-prefix: "product-docs/"
          prune: true

Tip: Put dry-run: true on pull request branches. The step then lists the files it would send, so a reviewer sees the effect before the branch is merged.

Removing It

Delete the asyntai/sync job from .circleci/config.yml. The entries already in your knowledge base stay. Remove them in Knowledge Base in your dashboard if you want them gone.

Plans & Pricing

The orb is free. It uses the Asyntai API, which needs the Starter plan or higher. View pricing.

Need Help?

If you have any questions or run into issues, contact us at [email protected].

Tài liệu