Skip to content

docs: smoke hosted Almanac GitHub App #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
rohans0509 wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: smoke hosted Almanac GitHub App #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
001ec56
docs: add hosted app live smoke note
rohans0509 Jun 5, 2026
fd38bd2
docs: retrigger hosted app smoke
rohans0509 Jun 5, 2026
09e4b70
Update Almanac from PR #12
almanac-bot[bot] Jun 5, 2026
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
10 changes: 9 additions & 1 deletion .almanac/pages/github-native-wiki-maintenance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,12 @@ sources:
- https://www.mintlify.com/docs/organize/settings
- https://www.mintlify.com/docs/deploy/github
- https://www.mintlify.com/docs/deploy/preview-deployments
- id: pr-12-hosted-app-smoke
type: pr
url: https://github.com/AlmanacCode/codealmanac/pull/12
note: Records the live same-repository smoke test for the hosted Almanac GitHub App update loop.
status: active
verified: 2026-05-29
verified: 2026-06-05
---

# GitHub-Native Wiki Maintenance
Expand Down Expand Up @@ -63,6 +67,10 @@ The remote product should make local wiki knowledge unavoidable at the moments w

The highest-value checks are not generic code review comments. They are docs-drift checks, invariant conflicts, missing decision or flow updates, stale pages, broken file references, and "this change deserves an Almanac update" signals. That keeps the product aligned with [[just-in-time-context-surfacing]]: a few cited constraints at action time, not broad context injection.

The 2026-06-05 hosted GitHub App smoke test narrowed the first production update loop. For v1 live delivery, a same-repository pull request receives one Almanac check, a maintainer approves the update, the hosted worker runs CodeAlmanac against the PR context, and the hosted backend commits only repo-owned Almanac files back to the PR branch [@pr-12-hosted-app-smoke]. Fork follow-up PR delivery is intentionally out of the first loop, and GitHub commits remain a backend responsibility rather than something delegated to local CLI code or a contributor-side agent [@pr-12-hosted-app-smoke].

The same smoke test exposed a GitHub API product constraint: check-action copy must stay within GitHub Check Runs API limits, so the PR-facing status should remain compact and point reviewers toward the wiki diff or hosted view instead of becoming a long report body [@pr-12-hosted-app-smoke].

## Canonical State Boundary

The default canonical state should stay in the same repository. The current implementation uses `.almanac/` for reviewed wiki source and local machinery, but the product boundary should be a configurable `almanac root` rather than a hard-coded hidden path. Same-repo ownership gives project memory the same branch, review, merge history, CODEOWNERS, blame, rollback, and access boundary as the code it describes.
Expand Down
9 changes: 9 additions & 0 deletions docs/research/2026-06-05-hosted-github-app-live-smoke.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
# Hosted GitHub App live smoke

This note records a live smoke test for the hosted Almanac GitHub App flow.

The expected behavior is that a same-repository pull request receives one Almanac check, the maintainer approves the update, the hosted worker runs CodeAlmanac against the PR context, and the backend commits only repo-owned Almanac files back to the PR branch.

The smoke test intentionally keeps delivery narrow: fork follow-up PR delivery is not part of v1, and the hosted backend remains the only component allowed to write GitHub commits.

The second smoke commit retriggers the pull request after the hosted backend check-action copy was shortened to satisfy GitHub's Check Runs API limits.
Loading