Doc Sync

Doc Sync is a GitHub Action that uploads markdown and text files from your repo into workspace knowledge. Unchanged files are skipped by checksum. Changed files replace the previous document with the same filename and labels. Use it when product specs, runbooks, or FAQs already live in git and you want agents to retrieve them without a manual upload step.

The mental model

Without Doc Sync	With Doc Sync
Upload each `.md` / `.txt` file from the dashboard or API	A workflow keeps knowledge in lockstep with the repo
Stale manuals stay indexed after a docs PR	Checksums skip unchanged files and replace the rest
Filenames and labels drift across uploads	The same path and tags identify a document on every run

How a run works

Collect files from paths (files, directories, or globs) relative to repo_dir.
List existing knowledge in the workspace and keep documents whose labels match tags.
For each local file, compare checksums against a remote document with the same filename.
Skip when the checksum already matches. Replace when it changed (delete the old document, then upload). Upload when the file is new.

Directories include .md, .mdx, .markdown, and .txt. Hidden directories, node_modules, and vendor are ignored. The document title is derived from the path (extension stripped; - and _ become spaces). The stored filename is the path relative to repo_dir.

Matching is scoped by filename and labels. The same path with different tags is a different document. Only documents that carry exactly the tags you pass are skipped, replaced, or cleaned up.

Set up the GitHub Action

Create an access key

In Settings → Access keys, create a key with knowledge permissions to list, upload, and delete documents.Copy the workspace id and the key secret (shown once). Use a dedicated key for this integration.

Add repository secrets

In the GitHub repo, add:

Secret	Value
`ACTX0_WORKSPACE_ID`	Workspace UUID
`ACTX0_ACCESS_KEY`	Workspace access key

Add a workflow

Copy this into .github/workflows/sync-docs.yml, or start from Actx0/doc-sync-example.Pull requests run in dry-run mode. Pushes to main upload and replace documents.

name: Sync docs to Actx0

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

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

      - uses: Actx0/[email protected]
        with:
          workspace_id: ${{ secrets.ACTX0_WORKSPACE_ID }}
          access_key: ${{ secrets.ACTX0_ACCESS_KEY }}
          tags: |
            tag: docs
            repo: ${{ github.repository }}
            team: platform
          paths: |
            docs/
          dry_run: ${{ github.event_name == 'pull_request' }}

Keep access keys in GitHub secrets. Do not commit them to the workflow file.

Inputs

Input	Required	Default	Description
`workspace_id`	Yes	—	Actx0 workspace id
`access_key`	Yes	—	Workspace access key
`paths`	Yes	—	Files, directories, or globs to sync, one per line
`tags`	No	empty	Knowledge labels, one `key: value` per line
`repo_dir`	No	`github.workspace`	Repository root used to resolve paths
`base_url`	No	`https://app.actx0.com`	Actx0 API base URL
`dry_run`	No	`false`	Compare checksums without uploading or deleting

paths examples:

paths: |
  docs/
  docs/*.md
  docs/file1.md
  README.md

A directory walk only picks markdown and text files. A glob or explicit file can select any matching path. A glob that matches nothing fails the step. tags become knowledge labels (key=value). Prefer a tag label so document search can filter the corpus:

tags: |
  tag: docs
  repo: ${{ github.repository }}
  team: platform

Outputs

Output	Meaning
`uploaded`	New documents created
`replaced`	Documents replaced after a checksum change
`skipped`	Documents whose checksum already matched
`failed`	Documents that failed to sync

The step also writes a job summary table. If any file fails, the action exits non-zero.

- uses: Actx0/[email protected]
  id: sync
  with:
    workspace_id: ${{ secrets.ACTX0_WORKSPACE_ID }}
    access_key: ${{ secrets.ACTX0_ACCESS_KEY }}
    paths: |
      docs/

- run: echo "uploaded=${{ steps.sync.outputs.uploaded }}"

Set dry_run: "true" to print skip / upload / replace actions without changing knowledge.

Run from a terminal

Use the CLI when you are not on GitHub Actions — from your machine or another CI system.

go install github.com/Actx0/doc-sync/cmd@latest

doc-sync \
  --workspace-id "$ACTX0_WORKSPACE_ID" \
  --access-key "$ACTX0_ACCESS_KEY" \
  --tags $'tag: docs\nteam: platform\nrepo: actx0/app' \
  --repo-dir . \
  --path docs/

--path is repeatable. --dry-run compares checksums without uploading. Flags match the action inputs above.

Next steps

Knowledge

How documents are chunked, indexed, and searched

Example repo

Sample docs and a workflow

Upload Document

Multipart upload, labels, and limits

Search Documents

Semantic retrieval over indexed chunks

​Doc Sync

​The mental model

​How a run works

​Set up the GitHub Action

​Inputs

​Outputs

​Run from a terminal

​Next steps

Knowledge

Example repo

Upload Document

Search Documents

Doc Sync

The mental model

How a run works

Set up the GitHub Action

Inputs

Outputs

Run from a terminal

Next steps