#542 Mirror GitHub issues and pull requests into timelines (#538)
–
- github
- github/openchronology/timeline-app
- github/openchronology/timeline-app#542
- pull request
- state:merged
The first work-item source for #538: GitHub issues and pull requests mirrored into timelines, read-only. This is stacked on #541 → #540 → #539 (ongoing durations); I'll retarget it as those merge. ## The mapping | On GitHub | On the timeline | | --- | --- | | An issue or PR is opened | A duration from its creation, **ongoing** | | Closed or merged | The duration ends then; reopened makes it ongoing again | | Edited, labelled, milestoned | Its title, notes and tags follow | | Assigned or unassigned | A moment, tagged `assigned` or `unassigned` and `assignee: ` | | A PR saying "closes #12" | A link to issue 12, when both are on the timeline | | An issue is deleted | Its duration is removed (webhook only) | - **Tags:** `github`, `repository:…`, `issue` or `pull request`, `state:…`, `assignee:…`, `label:…`, `milestone:…`. Separating by `assignee:` tags gives the per-person Gantt view the issue asked about, with no new view. - **IDs:** they come from the source (`gh: : : `), so a redelivered webhook and a re-run import update the same entities rather than adding copies. ## Pieces - **`server/github-source.mjs`:** the mapping, signature checks and routing rules (`owner/name` or `owner/*` → timeline, then a default), with no I/O. - **`server/github-receiver.mjs`** (`npm run github`), the webhook receiver: - it checks `X-Hub-Signature-256` (401 otherwise), answers 202 at once and coalesces changes per timeline; - it saves links apart, so a link to an issue the timeline doesn't hold is let go; - it retries 409, 429, 5xx and unreachable errors, and drains its queue on SIGTERM. - **`server/import-github.mjs`** (`och-import-github`), the backfill: - it reads issues and pull requests (`/issues?state=all`) and assignments (`/issues/events`), following `Link` pages; - options: `--since`, `--no-events`, `--dry-run`, a route file or `--timeline`; - it waits for a rate limit that resets within 15 minutes, and sends the token only to the GitHub API's origin (GitHub Enterprise through `GITHUB_API_URL`). - **`TimelineWriter.send`** can now delete durations and add links. - **Gregorian check:** both tools check that their timelines have the Gregorian display before writing. `docs/github.md` (also added to the help area) covers setup, the mapping, limits, and which personal data is copied: logins of assignees, titles and the start of each item's text. Comments and email addresses are not copied. ## Tests - **Unit:** 13 new tests in `test/github-source.test.mjs`, run against fake GitHub and OpenChronology APIs. They cover: - the mapping, IDs, "closes" parsing, signatures and routes; - receiver coalescing, retries, refused links, and HTTP end to end; - importer paging, `since`, links, the token and User-Agent, and the CLI's arguments and dry run. - **Real GitHub:** a dry run against this repository since 1 November read 125 items (12 open) and 51 links in 13 requests. - **`npm test`:** passes apart from `contents.test.mjs`, which fails locally with git `ENOBUFS`. ## Not in this PR - **Server packages:** deb, rpm, Homebrew, Nix, AUR and the Docker Compose service. The log tools ship in all of them; this one runs from a checkout or `npm` for now. - **More sources:** Microsoft Planner and kanban boards, using the same mapping. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011fFY8eruEi1xAkkMBni13B https://github.com/openchronology/timeline-app/pull/542
Related
- #12 Undo / Redo
- #538 Work-item sources: aggregate GitHub assignments, then Planner and kanban boards
- #539 Let a duration end "now", while it is ongoing (#537, stage 1)
- #540 Save ongoing durations on the server and resolve them at its clock (#537, stage 2)
- #541 Hold ongoing durations in desktop files, ending at the app's clock (#537, stage 3)
- #543 Mirror releases, milestones and time in board columns from GitHub (#538)
- Merge pull request #542 from openchronology/feature/github-source
Open #542 Mirror GitHub issues and pull requests into timelines (#538) in the timeline