GitHub in Roma
Read the repositories you choose, and open a change when you ask.
Connect GitHub, choose which repositories Roma may touch, and your operator can read them, answer from their history, issues and pull requests, and write to them when you ask, from any device. Every write opens a pull request for you to merge, and a destructive action is never offered.
What the operator does in GitHub
Sam keeps his notes in a repository. From his phone he says "Save an idea to my notes repo: a voice memo that turns into a shopping list". The operator reads the file the idea belongs in, appends the line in the file's own format, and shows a card with the file, what the write does to it and the text itself. He approves, and a pull request opens against the repository's default branch, with its link in the conversation.
"Fix the typo in the README" replaces the text. "Start tomorrow's post where the others live" creates a file. When a repository carries instructions for agents, an AGENTS.md at its root, the operator reads them first and follows the repository's own conventions.
Beyond files: "What changed in my notes repo this week?" lists the commits. The operator reads issues, pull requests, reviews, releases and code search results. It closes and reopens issues, sets labels and assignees, and updates an issue or a pull request. It creates issues, comments, reviews and releases, opens and merges pull requests, and re-runs a failed run of your checks, each when you ask.
A public repository you did not add can be read too. "Look at northwind/field-notes on GitHub, there is a checklist in it, turn it into a list" checks that the repository is public, reads it and builds the list. A write still needs the repository on your list.
Which repositories Roma may touch
GitHub's sign-in gives access to every repository your account can reach, public and private. The list on the connection's page is what limits Roma. It can only read and write the repositories listed there, plus reads of public ones, and the rule is checked on every call. Add repository searches your account's repositories, and × takes one off. Each row says which branch its pull requests go into and, when the repository carries agent instructions, that the operator follows them. Refresh instructions re-reads them after you edit them. Choosing repositories is done on the Mac or in the browser. Connecting and capturing work from the iPhone.
What asks first, and what it never does
Reading runs freely. Writing files always asks, with the content on the card, the one described in Approvals. So does anything that reaches other people: an issue, a comment, a review, a pull request, a merge, a release. Closing or reopening an issue, labels, and edits to an issue or a pull request run when you ask, unless you set Updating to Ask first on the connection's page. The operator never deletes, archives or transfers anything, on any repository, and it never commits straight to a branch: a write is a pull request you merge. It is not a programmer. It writes text files, one commit each, and runs no builds or tests.
How to connect
Open Settings → Connections and press GitHub. Sign in with GitHub in the window that opens, allow the access it lists, and close the page when it says Connected. Then press the row and add the repositories Roma may touch. The permissions sit under the list. The iPhone's Settings → Connections carries the same row. The general steps are in Connect an app to Roma, and the public page is /connections/github.
How to disconnect
Settings → Connections, press GitHub, then Disconnect. Roma's access ends at once, and the repository list goes with it. Pull requests and issues it opened stay on GitHub.
Questions people ask
Does Roma commit to my main branch?
No. Every write opens a pull request into the repository's default branch. You merge it on GitHub, or ask the operator to, which shows a card first.
Can it read a repository I did not add?
Only a public one. The operator checks that the repository is public, then reads. A private repository has to be on your list, and a write needs the list whatever the repository's visibility.
What happens if a file changed while Roma was writing?
It reads the file again, applies the write again and retries once. If the file keeps moving, it tells you the file changed while it was writing rather than overwriting it.
Can I choose repositories from my iPhone?
Connecting works from the iPhone, and so does a capture into a repository already on your list. Choosing the repositories is done on the Mac or in the browser.