Azure DevOps Integration

Send your documentation to your chatbot on every pipeline run

Overview

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

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

How It Works

The task is one step in your pipeline. It 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 adds an Asyntai Knowledge Sync tab to the run page that lists every page it added, updated, or left alone.

Requirements

An Azure DevOps organization with Azure Pipelines
A Microsoft-hosted agent, or a self-hosted agent version 3.232.1 or later
An Asyntai account on the Starter plan or higher, because the task uses the Asyntai API

Installation

Follow these steps to add the task to your pipeline:

Install the Extension

Open Asyntai Knowledge Sync in the Visual Studio Marketplace, press Get it free, and choose your Azure DevOps organization.

Get Your API Key

Add a Secret Variable

In Azure DevOps, open your pipeline, press Edit, then Variables, then New variable. Name it ASYNTAI_API_KEY, paste your key as the value, and tick Keep this value secret.

Add the Task

Add the task to azure-pipelines.yml:

steps:
  - task: AsyntaiKnowledgeSync@1
    inputs:
      files: |
        docs/**/*.md

In the classic editor, search for Asyntai Knowledge Sync in the task list instead.

Run and Watch

Run the pipeline. Open the run and the Asyntai Knowledge Sync tab. It counts how many entries the run added, updated, or left alone.

Settings

Input	Default	What it does
`apiKey`	`$(ASYNTAI_API_KEY)`	Your Asyntai API key, read from the secret variable.
`files`	`docs/*/.md`	File patterns to send, one per line. Supports ``, `?` and `*`.
`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.
`websiteId`	empty	Which website to fill. Empty means the primary website of the account.
`rootDirectory`	`$(Build.SourcesDirectory)`	The folder the file patterns start from.

The task also sets the output variables added, updated, unchanged and deleted. Give the step a name to read them in later steps.

Several Repositories, One Chatbot

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

- task: AsyntaiKnowledgeSync@1
  inputs:
    files: 'docs/**/*.md'
    titlePrefix: 'product-docs/'
    prune: true

Check Pull Requests First

Add the task a second time with dryRun on and a condition. On a pull request build, the task lists the pages it would send, so a reviewer sees the effect before the merge.

- task: AsyntaiKnowledgeSync@1
  displayName: Preview the knowledge sync
  condition: eq(variables['Build.Reason'], 'PullRequest')
  inputs:
    files: 'docs/**/*.md'
    dryRun: true

- task: AsyntaiKnowledgeSync@1
  displayName: Sync the knowledge base
  condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
  inputs:
    files: 'docs/**/*.md'

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

Removing It

Delete the task from your pipeline. To remove the extension, open Organization settings → Extensions, select Asyntai Knowledge Sync, and press Uninstall. The entries already in your knowledge base stay. Remove them in Knowledge Base in your dashboard if you want them gone.

Plans & Pricing

The extension 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