Why is my GitHub KB sync not working?
When a GitHub-to-Atender KB sync pipeline misbehaves, the cause is almost always one of five known gotchas: an article missed past the 500-item list limit, a duplicate category after a rename, embedding lag, translations that never sync automatically, or an API key that leaked into a commit. Each has a quick fix below. This FAQ assumes the setup from Push articles from a GitHub repo.
Why did a push create a duplicate instead of updating the article?
The push script lists 500 articles by default when building its slug lookup. Once your KB crosses 500 articles, the list call misses entries, the script doesn’t find the existing slug, and it creates a new article instead of updating. Fix: paginate the list call in the push script so the slug lookup sees every article.
Why do I have two categories with almost the same name?
Categories upsert by name, not slug. If you rename a category in an article’s frontmatter without updating the existing articles, the script creates a duplicate category on the next push. Fix: keep category names stable in frontmatter, and use exactly the same spelling across all articles in a category.
The article is live in the help center — why doesn’t the AI use it yet?
Embeddings catch up in the background. A pushed article appears in the UI within seconds, but it appears in AI retrieval within a minute or two. Wait a moment and re-test; see also When do articles update for AI agents?.
Why are translations not updating after a push?
The doc-as-code path doesn’t auto-trigger translation sync. After a push, click Sync Translations in Settings → Knowledge → Markets and Languages. You can wire a workflow step to call the sync endpoint instead — but be cautious: triggering sync on every push during a bulk update can pile up jobs. Most teams run sync manually after a content batch.
I committed the API key. What now?
Rotate the key immediately — a key that has been in a commit is not a secret anymore, even after you delete the file. Generate a fresh key, update the ATENDER_API_KEY repository secret, and only ever inject the key via that secret.