Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .github/docs-sync.md
Original file line number Diff line number Diff line change
@@ -1,26 +1,26 @@
# Notify the Uniskela documentation site

stack-manager's user documentation is published at [uniskela.com/docs/stack-manager](https://uniskela.com/docs/stack-manager/)
by `uniskela/.com`, the same way as adhd-hub and ts6-manager.
by `uniskela/com`, the same way as adhd-hub and ts6-manager.

- [`docs/manifest.json`](../docs/manifest.json) lists the pages to publish: `source` file, URL `slug`, sidebar `title`
and `group`. Published pages live under `docs/public/`. `docs/internal/` (plans, architecture decisions) and
`docs/agents/` are not imported; links to them fall back to GitHub URLs on the site.
- The `Notify Uniskela documentation` workflow sends an update notification after README/docs changes merge to
`main` (and on each published release). It does not publish the website directly: `uniskela/.com` imports the
`main` (and on each published release). It does not publish the website directly: `uniskela/com` imports the
content, runs its checks and proposes a draft PR for review.

## One-time setup

1. In `uniskela/.com`, add `uniskela/stack-manager` to the receiver's list of documentation sources and select its
1. In `uniskela/com`, add `uniskela/stack-manager` to the receiver's list of documentation sources and select its
pages (see `docs/docs-dispatch-setup.md` in that repository).
2. In this repository, configure the Actions variable `DOCS_SYNC_APP_CLIENT_ID` and the Actions secret
`DOCS_SYNC_APP_PRIVATE_KEY` for the dedicated documentation GitHub App (installed only on `uniskela/.com` with
`DOCS_SYNC_APP_PRIVATE_KEY` for the dedicated documentation GitHub App (installed only on `uniskela/com` with
Contents read/write). The workflow creates a short-lived, destination-only installation token, which is revoked
after the job. It never runs on pull requests or forks and does not check out source code.
3. Run the workflow manually on `main` and verify the receiver in `uniskela/.com` succeeds.
3. Run the workflow manually on `main` and verify the receiver in `uniskela/com` succeeds.

Missing credentials make the workflow fail visibly. The weekly sync in `uniskela/.com` remains a fallback. GitHub does
Missing credentials make the workflow fail visibly. The weekly sync in `uniskela/com` remains a fallback. GitHub does
not start push-triggered workflows for pushes made with `GITHUB_TOKEN`; use a manual run in that case.

Never put the App private key in repository files, PRs or chats.
Expand Down
6 changes: 3 additions & 3 deletions .github/workflows/notify-uniskela-docs.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: Notify Uniskela documentation
# Tells uniskela/.com that README/docs changed so it can import them (see .github/docs-sync.md).
# Tells uniskela/com that README/docs changed so it can import them (see .github/docs-sync.md).
# Sends only the repository, commit and ref: no checkout, never runs on pull requests or forks.
on:
push:
Expand Down Expand Up @@ -49,7 +49,7 @@ jobs:
client-id: ${{ vars.DOCS_SYNC_APP_CLIENT_ID }}
private-key: ${{ secrets.DOCS_SYNC_APP_PRIVATE_KEY }}
owner: uniskela
repositories: .com
repositories: com
permission-contents: write
- name: Notify the documentation receiver
env:
Expand All @@ -60,4 +60,4 @@ jobs:
run: |
jq -n --arg repository "$SOURCE_REPO" --arg sha "$SOURCE_SHA" --arg ref "$SOURCE_REF" \
'{event_type:"docs-source-updated",client_payload:{repository:$repository,sha:$sha,ref:$ref}}' > "$RUNNER_TEMP/docs-dispatch.json"
gh api --method POST repos/uniskela/.com/dispatches --input "$RUNNER_TEMP/docs-dispatch.json"
gh api --method POST repos/uniskela/com/dispatches --input "$RUNNER_TEMP/docs-dispatch.json"
Loading