GitHub integration

Installing the GitHub App and turning issues into payable tasks.

The GitHub page (community sidebar → GitHub) connects a community to GitHub so that issues on a project board become payable tasks without anyone retyping them. It is admin-only.

Installing the GitHub App

If the community has no installation yet, the page shows Install GitHub App. Click it, choose the GitHub organisation or account and the repositories it may access, and you are sent back here. The page then shows "Installed on …" and lists every repository the installation can see.

A community can connect several GitHub organisations or accounts — use Add another organisation and repeat the install for each one. This is for workgroups whose code lives in different organisations but which are all paid from the same treasury: repositories from any connected organisation can be linked to any workgroup, including a workgroup fed by two organisations at once.

Finish on GitHub within 10 minutes, in the same browser and signed in with the same wallet: the return trip is tied to the admin who started it. An installation that already belongs to another community is never moved (the page says so), and an existing installation that no community holds is accepted only if it was installed or updated on GitHub in the last 15 minutes. If the page says the installation was not recent, open Install GitHub App again and save the installation on GitHub.

If GitHub only offers your personal account and not the organisation, you are most likely not an owner of that organisation — because the app asks for organisation project access, only an organisation owner can install it there, so ask an owner to run the install (or to make you an owner). If you are an owner and the organisation is still not offered, the GitHub App itself is set to install only on the account that owns it; on the hosted app, contact the Treasury Guild operator, and on your own deployment set the app to Any account (make it public) in its GitHub App settings.

The app needs read and write access to issues (to comment the payment back later), to repository contents (to publish frozen tally records into a community's chosen archive repository when Governance settings use GitHub), and to project boards (to move paid issues to the Paid column). Existing installations must approve a new Contents permission on GitHub before archive publication works.

Disconnecting or changing organisation

Each connected organisation has its own Disconnect beside its "Installed on …" heading. Click it and confirm. Disconnecting one organisation:

• uninstalls the Treasury Guild app from that GitHub organisation or account (on GitHub as well, not just here),
• removes this community's repository and project links for that organisation, so its syncing and payment write-back stop, and
• turns workgroups that were fed only by that organisation back into app boards (a workgroup still fed by another organisation stays a GitHub board).

Other connected organisations are unaffected. Tasks already imported and their payment history stay — they are frozen: they are no longer updated from GitHub, but nothing is deleted and anything already payable stays payable. Disconnecting also works when the app was already uninstalled on GitHub; uninstalling it there yourself has the same effect here.

To change an organisation: disconnect it, then click Install GitHub App (or Add another organisation) again, choose the correct organisation and repositories, re-link each repository to its workgroup and click Full sync.

Linking a repository to a workgroup

Each repository card has:

Click Link (or Update after changes); the button stays disabled until a workgroup is chosen. A linked repository also shows Full sync, which re-reads the whole project immediately and reports "Synced N issues, removed M". Linking does not import existing issues at once: click Full sync after linking, or wait for the next hourly sweep.

Repositories linked to an archived workgroup are paused until the workgroup is restored.

Which issues become tasks

An issue is imported as a task only when both conditions hold:

1. it sits in the import status column of a Projects v2 board that includes the repository, and
2. it carries the payable label.

Imported tasks are immediately payable. When an issue loses the label or leaves the column, its task is removed again, unless it has already been queued, paid or reconciled, or still has payout rows from a rejected transaction. Queued, paid and reconciled tasks keep mirroring only their GitHub text, labels and column. An unpaid task retained solely because it has payout rows is left unchanged while it is outside the import filter.

Bounties come from the project board's number fields: every number field with a positive value is stored as a bounty amount under the field's name. At payout the field name is matched to a token by ticker, case-insensitively: ADA is built in, a field whose name matches the ticker of exactly one token the treasury holds is connected automatically, and anything else has to be connected by hand on Payday. Admins and leads can also create a number field from a wallet token (or ADA) in the issue dialog: pick the token, name the field (defaults to the ticker), and confirm — that adds the field on the GitHub project unless one with that name already exists, and remembers the token mapping for payouts.

Assignees mirror the issue's GitHub assignees. Each one is paid to the wallet linked to that GitHub account (see linking a GitHub account); until they link, the task shows Not linked and cannot be paid. The linked wallet is filled in only while the assignee's wallet is empty, so a wallet set by hand in the task dialog is never overwritten by the sync. Admins and leads can change GitHub assignees from the task dialog (from people assignable on the issue's repository) and can additionally add manual assignees the sync never touches.

How syncing works

• Webhooks update tasks within seconds of a change on GitHub.
• An hourly sweep re-syncs linked repositories that were never synced or not synced in the last six hours (up to five per run) and repairs anything a webhook missed. Webhooks are never the only source of truth.
• Full sync on a repository card runs the same full re-read for that repository right now.

Managing issues from Treasury Guild

Admins and a workgroup's leads can also create and edit issues without leaving Treasury Guild; every change is saved to GitHub first and then synced back, so the two never disagree about which is newer. Task proposals do not create issues here: they only add tasks on app boards. After a community vote about work on a GitHub board, create the issue with Add an issue… (or on GitHub) as usual.

• Add an issue from a project column's Add issue… box (title only, Enter to create). The new issue opens on the linked repository and lands in that column's Status on the project. When the workgroup has more than one linked repository, pick which one in the column footer first. Creating an issue does not apply the payable label: it becomes a payable task here only once it also matches the import rule. Description, labels, assignees and bounty fields are edited afterwards in the dialog.
• Open an imported task (its card on the board, or on Payday) to edit the issue's title, description, labels, assignees and — when the project's columns are loaded — its project status, plus its bounty number fields (including adding another of the project's unused number fields as a bounty token, or creating a new number field from a wallet token). Only the fields you changed are sent. Payout wallets, extra manual assignees and the budget month are edited here as before.
• Drag a card between project columns on the board to move the issue to that Status on GitHub. The card moves straight away and shows Saving to GitHub… while the change is written; if GitHub cannot be updated, the card returns to its column.
• Open a board item that is not a task yet to edit its title, labels, open/closed state, assignees, status and bounty fields. Draft issues and pull requests cannot be edited here.
• The import rule applies in both directions: moving an issue out of the import column or removing its payable label removes its unpaid task here, and giving an issue both the payable label and the import column imports it as a task.
• Once a task is queued in a payout or paid, only its title and description can still be edited here — its status, labels, state, assignees and bounty are part of the payment record. Anyone can still change them on GitHub, and the sync mirrors the text from there.

What happens after payment

When a payout transaction is confirmed on-chain, Treasury Guild comments the transaction hash on each paid issue, adds a paid label and moves the issue's project item to the repository's Paid status column. The write-back is done by the background job that runs every 15 minutes, so it lands a few minutes after confirmation; if GitHub was unreachable it is retried on the next run.

The move only happens when the project's Status field has an option with that name (matched case-insensitively), the task recorded which project item it was imported from, and the GitHub App has write access to projects. Otherwise the comment and label are still written and the issue stays in its column. The task itself is never removed: paid issues keep mirroring their title, labels and column in Treasury Guild.

Related: Workgroups & boards, Payday.