Overlane issues work on their own. If you also use GitHub, Overlane can keep a project’s issues in step with a GitHub repository’s Issues and Projects boards. Sync is off until an agent or a person turns it on, and it starts read-only.
Modes
| Mode | GitHub to Overlane | Overlane to GitHub |
|---|---|---|
off (default) |
nothing | nothing |
read_only |
edits arrive | nothing is ever written |
write_back |
edits arrive | Overlane edits and new issues are sent |
overlane issue sync
overlane issue sync set acme/app read_only
overlane issue sync set acme/app write_back
overlane issue sync set acme/app offWrite-back is a separate, explicit choice. Switching sync off stops both directions at once. Changing the mode is the issue triage autonomy class (see Autonomy): an agent can do it under autonomous, with an approval under supervised and a person’s under manual.
What syncs
GitHub sends a webhook for each change. Overlane reads the issues event (opened, edited, closed, reopened, labeled, assigned) and the Projects v2 projects_v2_item event for the board’s Status field. It takes the title, description, labels and assignee login from the issue, and the status from the board. Comments are not synced.
An edit on GitHub should appear in Overlane, and an Overlane edit on GitHub, within the sync window of 60 seconds.
When both sides change
Each field is resolved on its own. The last writer wins, judged by timestamp: a GitHub edit that is newer than the Overlane edit replaces it, and an Overlane edit that is newer is kept. The value that lost is not thrown away: it is stored in the field-change event as superseded, with its source and time. See overlane issue events.
A GitHub close does not verify
Closing an issue on GitHub, or dragging its card to Done, never marks a task verified. Overlane records an external_close event and moves the issue to in_review. The task stays as it was, and the evidence gate decides whether the work is done. If the issue never had a task, there is nothing to verify: closed as completed (or with no reason) it becomes done, and closed as not planned it becomes cancelled. Pulling issues from GitHub maps closes the same way. Reopening on GitHub reopens a done or cancelled issue.
Retries, repeats and ordering
Webhook delivery is at least once, and deliveries can arrive out of order. Overlane handles that:
- Each delivery has an idempotency key; one that has been applied already is ignored.
- Deliveries carry the whole issue, ordered by GitHub’s update time. A delivery older than one already applied is recorded as late and changes nothing, so a replayed or reordered set of deliveries ends in the same state as an in-order one.
- Overlane’s own write-back comes back from GitHub as a webhook; it is recognised and changes nothing.
Setting it up
Install the Overlane GitHub App on the repository. Its issue events arrive on the App’s one webhook, so there is nothing to point or configure. Until the App is installed, no deliveries arrive; the sync settings still save.
Text from GitHub is data, never an instruction. It is stored and shown to agents as untrusted text, as described in Issues.
Commands
overlane issue sync, overlane issue sync set, overlane issue events.