> ## Documentation Index
> Fetch the complete documentation index at: https://docs.actx0.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Doc Sync
> Sync repository docs into an Actx0 workspace knowledge base from GitHub Actions.
## Doc Sync
[Doc Sync](https://github.com/Actx0/doc-sync) is a GitHub Action that uploads markdown and text files from your repo into [workspace knowledge](/platform/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
1. Collect files from `paths` (files, directories, or globs) relative to `repo_dir`.
2. List existing knowledge in the workspace and keep documents whose labels match `tags`.
3. For each local file, compare checksums against a remote document with the same filename.
4. **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
In [Settings → Access keys](https://app.actx0.com/settings), 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.
In the GitHub repo, add:
| Secret | Value |
| -------------------- | -------------------- |
| `ACTX0_WORKSPACE_ID` | Workspace UUID |
| `ACTX0_ACCESS_KEY` | Workspace access key |
Copy this into `.github/workflows/sync-docs.yml`, or start from [Actx0/doc-sync-example](https://github.com/Actx0/doc-sync-example).
Pull requests run in dry-run mode. Pushes to `main` upload and replace documents.
```yaml theme={null}
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/doc-sync@v1.0.0
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:
```yaml theme={null}
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](/platform/knowledge#labels-and-filters) can filter the corpus:
```yaml theme={null}
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.
```yaml theme={null}
- uses: Actx0/doc-sync@v1.0.0
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.
```zsh theme={null}
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
How documents are chunked, indexed, and searched
Sample docs and a workflow
Multipart upload, labels, and limits
Semantic retrieval over indexed chunks