Jenkins Integration

Send your documentation to your chatbot on every build

Overview

Your documentation lives in a repository. Your chatbot answers from the Asyntai knowledge base. The Asyntai Knowledge Sync plugin for Jenkins keeps the two the same.

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

How It Works

The plugin adds one build step, asyntaiKnowledgeSync. It works in Pipeline jobs and in freestyle jobs. 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 build page shows a table of every page the step added, updated, or left alone.

Requirements

Jenkins 2.555.3 or later
The Credentials and Plain Credentials plugins, which Jenkins installs with the plugin
An Asyntai account on the Starter plan or higher, because the step uses the Asyntai API

Installation

Follow these steps to add the step to your job:

Install the Plugin

In Jenkins, open Manage Jenkins → Plugins → Available plugins, search for Asyntai Knowledge Sync, tick it, and press Install.

Get Your API Key

Add a Credential

Open Manage Jenkins → Credentials, choose a domain, and press Add Credentials. Set the kind to Secret text, paste your key as the secret, and set the ID to asyntai-api-key.

Add the Step

Add the step to your Jenkinsfile, after the checkout:

pipeline {
  agent any
  stages {
    stage('Sync docs') {
      steps {
        asyntaiKnowledgeSync credentialsId: 'asyntai-api-key',
          files: 'docs/**/*.md'
      }
    }
  }
}

In a freestyle job, press Add build step and choose Asyntai Knowledge Sync instead. The Test connection button checks the key before you save.

Build and Watch

Run the job. The build page shows how many entries the build added, updated, or left alone, with one line for each page.

Settings

Parameter	Default	What it does
`credentialsId`	required	The Secret text credential that holds your Asyntai API key.
`files`	`docs/*/.md`	File patterns to send, one per line or separated by commas. Supports ``, `?` and `*`.
`excludes`	empty	File patterns to leave out, for example `docs/drafts/**`.
`titlePrefix`	empty	Text put in front of every entry title. Use it when several repositories feed one chatbot.
`prune`	`false`	Delete entries whose file is gone. Needs `titlePrefix`.
`dryRun`	`false`	List the changes and send nothing.
`rootDirectory`	the workspace	The folder the file patterns start from, relative to the workspace.
`websiteId`	empty	Which website to fill. Empty means the primary website of the account.

Several Repositories, One Chatbot

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

asyntaiKnowledgeSync credentialsId: 'asyntai-api-key',
  files: 'docs/**/*.md',
  titlePrefix: 'product-docs/',
  prune: true

Check Pull Requests First

In a multibranch Pipeline, run the step with dryRun on pull requests and for real on your main branch. On a pull request, the build lists the pages it would send, so a reviewer sees the effect before the merge.

stage('Sync docs') {
  steps {
    asyntaiKnowledgeSync credentialsId: 'asyntai-api-key',
      files: 'docs/**/*.md',
      dryRun: env.CHANGE_ID != null
  }
}

Tip: Built documentation works too. Build your site in an earlier stage, set rootDirectory to the output folder, and set files to **/*.html.

Removing It

Delete the step from your job. To remove the plugin, open Manage Jenkins → Plugins → Installed plugins and uninstall Asyntai Knowledge Sync. 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