Knowledge Baseadvanced

Push articles from a GitHub repo

A working doc-as-code setup. Markdown articles in a GitHub repo, a Python push script, a GitHub Actions workflow that syncs to Atender's v1 API on every push to main. Copy-paste workflow inside.

8 min read

Push articles from a GitHub repo

To push Markdown articles from a GitHub repo to your Atender Knowledge Base automatically, you wire together three pieces: a KB API key stored as a repository secret, a push script, and a GitHub Actions workflow that runs the script on every commit to main. This recipe sets up all three end to end — the shape is portable to any CI system. The payoff is doc-as-code: Git version history, PR review on doc changes, and CI checks — see Doc-as-code with the KB API for the why.

What you’ll end up with

  • A /articles/ folder in a GitHub repo with one Markdown file per article.
  • A Python push script under /scripts/push_kb.py that reads articles and upserts them.
  • A GitHub Actions workflow that runs the script when articles change.
  • A repository secret holding your Atender API key.

Total setup time: about 30 minutes if you’re comfortable with GitHub Actions; an hour from cold.

Step 1 — Generate the API key

Follow Generate a KB API key. You want a key with both knowledge:read (to list existing articles for slug lookups) and knowledge:write (to create and update).

Name it something obvious: github-actions-kb-sync. Copy the key once when shown — you can’t retrieve it again.

Step 2 — Add the key as a GitHub secret

In your GitHub repo:

  1. Go to Settings → Secrets and variables → Actions.
  2. Click New repository secret.
  3. Name: ATENDER_API_KEY.
  4. Value: the sa_live_... key you copied.
  5. Save.

Step 3 — Lay out the repo

.
├── articles/
│   ├── billing/
│   │   ├── how-to-update-payment.md
│   │   └── concept-invoices.md
│   ├── shipping/
│   │   ├── how-to-track-an-order.md
│   │   └── faq-shipping-times.md
│   └── ...
├── scripts/
│   └── push_kb.py
└── .github/
    └── workflows/
        └── push-kb.yml

Each Markdown file carries frontmatter at the top:

---
title: "How to update your payment method"
slug: "update-payment-method"
category: "Billing"
type: "how-to"
summary: "Open Account → Billing → Change."
keywords: [payment, credit card, billing]
ux_path: "Account → Billing → Payment methods"
roles: [admin]
status: "published"
---

Step 4 — The push script

Save the script from Python push script for the KB API as scripts/push_kb.py. It walks every Markdown file under articles/, upserts categories by name, and creates or updates each article matched by slug. It needs two pip packages: python-frontmatter and requests — the workflow below installs them.

Step 5 — The GitHub Actions workflow

.github/workflows/push-kb.yml:

name: Push KB to Atender

on:
  push:
    branches: [main]
    paths:
      - "articles/**"
      - "scripts/push_kb.py"
  workflow_dispatch:

jobs:
  push:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install python-frontmatter requests

      - name: Push to Atender
        env:
          ATENDER_API_KEY: ${{ secrets.ATENDER_API_KEY }}
        run: python scripts/push_kb.py

Commit it, push to main, and the workflow runs on every change to articles/ or the script. Use workflow_dispatch to run it manually from the Actions tab.

Step 6 — Try it

  1. Add an article under articles/billing/how-to-update-payment.md with the frontmatter shape above.
  2. Commit and push to main.
  3. Watch the Actions tab. The job should print c update-payment (created) on the first run.
  4. Open your Atender help center. The article should appear in the Billing category within a minute (after embeddings catch up).
  5. Edit the article, commit, push. The job prints u update-payment (updated) and the change goes live within a minute.

Trim it down

The minimum viable version of this recipe:

  • A single Markdown file in a repo.
  • One CLI call: ATENDER_API_KEY=... python scripts/push_kb.py.
  • No CI yet — run locally until the loop feels right.

Add the GitHub Actions wrapper once you trust the script.

When something misbehaves

The pipeline has a handful of known gotchas: the article list call needs pagination once you cross 500 articles, category renames create duplicates, embeddings lag the UI by a minute or two, and translation sync is never automatic — after a push you trigger it yourself. Symptoms and fixes are collected in Why is my GitHub KB sync not working?.

See also

Tags

AdvancedRecipe
Back to Knowledge Base