Buildkite 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 AI Docs Sync plugin for Buildkite 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 customers get the current answer.

How It Works

The plugin runs as one step in 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 build 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 puts a summary on the build page, for example 2 added, 1 updated, 14 unchanged.

Requirements

A Buildkite pipeline, with agents that have bash and Python 3
An Asyntai account on the Starter plan or higher, because the plugin uses the Asyntai API

Installation

Follow these steps to add the plugin to your pipeline:

Get Your API Key

Give the Key to Buildkite

In Buildkite, open your cluster, then Secrets, and add a secret named ASYNTAI_API_KEY with your key as the value. You can also set ASYNTAI_API_KEY in the agent environment hook instead.

Add the Step

Open .buildkite/pipeline.yml and add a step:

steps:
  - label: ":books: Sync docs to Asyntai"
    branches: main
    plugins:
      - asyntai/ai-docs-sync#v1.0.0:
          path: docs
          api-key-secret: ASYNTAI_API_KEY

Leave out api-key-secret if you set the key in the agent environment hook.

Push and Watch

Push the change. Open the build in Buildkite. The step shows each file it sent, and the build page shows a summary of the run.

Settings

Option	Default	What it does
`path`	required	The file or folder to read, relative to the checkout.
`patterns`	`.md,.mdx,*.txt`	File patterns to include, as a list or a comma separated string.
`exclude`	empty	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-secret`	empty	The name of a Buildkite secret that holds your key.
`api-key-env`	`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.
`annotate`	`true`	Put a summary of the run on the build page.

Several Repositories, One Chatbot

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

      - asyntai/ai-docs-sync#v1.0.0:
          path: docs
          title-prefix: "product-docs/"
          prune: true

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

Removing It

Delete the step from .buildkite/pipeline.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 plugin 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].

Documentation