Docs
Docs menu

GitHub

Connect GitHub to a node, import repositories that keep following GitHub, send approved changes back as pull requests, and unlink a repository.

A repository can stay on GitHub while you use Moru for agent work and review. Moru calls such a repository linked: GitHub remains the source of truth for its branches, and Moru sends approved changes back to it.

How a linked repository works#

  • Branches and tags follow GitHub. The node fetches from GitHub about once a minute, before every Bake-off and before sending a change back. Fetch now in the bar at the top of the repository fetches at once.
  • Nobody pushes branches to the node. A push of a branch or tag is refused with “this repo follows github.com/org/app; push … there instead”. Push to GitHub, and the node picks it up.
  • Approved changes go back to GitHub. On a linked repository, a change page offers Open a pull request for r1 where it would offer Merge r1. Moru rebases the change onto GitHub’s current target branch, pushes it as moru/<change-id> and opens a pull request. Its description carries the change’s description, the request and its acceptance criteria, the Bake-off ranking when there was one, who approved it, and how the agent ran.
  • The change merges when the pull request merges. Until then its status is Proposed. Merge the pull request on GitHub as usual.
  • Moru’s own data stays on the node under refs/moru/, unless you choose to keep a copy on GitHub too.

Instead of pull requests, a repository can deliver by direct push: approved changes are pushed straight to the target branch. GitHub’s branch protection may refuse them.

Connect GitHub#

Site admins connect GitHub accounts and organizations under GitHub connections in the account menu. Each connection is a GitHub App that the node registers for you.

The node needs a public HTTPS address that GitHub can send people back to. GitHub doesn’t accept localhost. It uses the node’s --public-url, or --github-public-url if you set one (MORU_PUBLIC_URL, MORU_GITHUB_PUBLIC_URL). See Configuration. A node at localhost, such as one you’re trying on your laptop, links repositories with a token instead.

To connect:

  1. Under Who imports through it, choose Site admins or Everyone on this node (see below).
  2. Under Owned by, choose My account or An organization, and give the organization’s name. You need to be an owner of it.
  3. Choose Continue on GitHub. GitHub shows the app it’s about to create from a ready-made form. Confirm it there.
  4. Install the app on the repositories you want in Moru. GitHub brings you back to Import from GitHub.

The app asks for read and write access to contents and pull requests, and read access to metadata. The node keeps the app’s private key and mints short-lived tokens from it when it needs them, which expire within an hour. Pull requests come from the app’s bot.

Site admins only#

A Site admins app is a private GitHub App. Only the account that owns it can install it, so connect each account or organization you import from. Only site admins import through it.

Everyone on this node#

An Everyone on this node app is a public GitHub App that any GitHub account can install. It lets people who aren’t site admins import their own repositories:

  • They choose Connect your GitHub account on Import from GitHub. Moru uses that connection to ask GitHub which repositories they can reach through the app and whether they can write to them. It keeps it in memory for an hour at most and never stores it.
  • They see the repositories of every account and organization where the app is installed, and can import the ones they have write access to on GitHub.
  • Imported repositories sync and deliver through the app, not through the person’s GitHub account.

The app’s name and page on GitHub are public. Edit its page on GitHub to say what installing it grants: an organization that installs it lets each of its members with write access import its repositories here. A node has one such app. Registering another replaces it, after you confirm; repositories already imported through the old one keep syncing through it.

The node keeps the app’s private key and client secret under secrets/github/apps/ in its data directory. Anyone with either can act for every installation of the app: protect and back up that directory like the node’s keys.

Disconnect an app#

When an app is renamed or deleted on GitHub, choose Disconnect next to it on the GitHub page. The node forgets the app and deletes its private key (and client secret, for the app for everyone). The app itself isn’t touched on GitHub: delete it there too if it should go for good.

Repositories linked through the app stay linked, with their code and Moru data, but they stop syncing with GitHub. The dialog lists them. Each one says so in its bar; to get it syncing again, connect an app that covers it and choose Use the GitHub App there, or unlink it.

Import repositories#

Open Import from GitHub from Bring your repositories on the home page, or with Import repositories on the GitHub page. Site admins see every installation of the node’s apps; everyone else sees what the app for everyone reaches.

  1. Tick the repositories to import. Each gets a Moru name you can change after as. Repositories already imported say so, and ones you can’t write to on GitHub can’t be picked.
  2. Choose the Owner in Moru: you, or an organization where you may create repositories.
  3. Choose Visibility. Private means only the owner and the people they add can see it in Moru, whatever it is on GitHub.
  4. Choose how Approved changes go to GitHub as: Pull requests or Direct pushes.
  5. Optionally tick Keep Moru’s data on GitHub too. Moru then pushes its requests, Bake-offs, reviews and attestations to hidden refs/moru/* refs on GitHub, and brings in any already there. Anyone who can read the GitHub repository can read them.
  6. Choose Import 1 repository (or however many you picked). The repositories appear at once; the first fetch from GitHub runs in the background.

To add repositories later, use Add or remove repositories on GitHub next to the installation, then Refresh.

With a personal access token#

Site admins who can’t register an app can link one repository with a token instead, under Advanced: link with a personal access token on the same page. On a node at localhost with no app connected, the page leads with it as Link a repository.

  1. Type the repository’s owner/name on GitHub under GitHub repository.
  2. Create a token on GitHub opens GitHub’s form for a fine-grained token, filled in: owned by the repository’s owner, with Contents, Pull requests and Workflows set to read and write, for 90 days. GitHub can’t preselect the repository: under Repository access, choose Only select repositories and pick it. Workflows lets changes that edit .github/workflows/ go back to GitHub.
  3. Paste the token under Token and choose Link repository. The node checks that the token can read the repository before it links anything.

Without a token#

A public repository can be followed with no token at all: leave Token empty and choose Follow without a token. The node fetches its branches and tags like any other linked repository, and agents work on it as usual. Nothing can go back to GitHub yet, so approving a change stops short of the pull request: the change, the request and the repository’s bar say so and offer Add a token to repository admins who are also site admins. Once a token is stored, the repository is an ordinary one linked with a token. A private repository can’t be read without a token, so it can’t be linked this way.

With the GitHub CLI, gh auth token prints a token that works as well, though it reaches every repository your account can. The node stores the token on its own disk and never shows it again. Pull requests then come from the token’s owner.

A repository linked with a token can move onto a GitHub App later: once an app is connected, repository admins who are also site admins see Use the GitHub App in the repository’s bar. The stored token is deleted.

From the command line#

moru-node link-github links a repository with a token file, creating the repository in Moru from GitHub if it doesn’t exist:

moru-node --data /var/lib/moru link-github acme/timetable acme-corp/timetable --token-file gh-token

The first argument is the name in Moru, the second owner/name on GitHub. The token can also come from MORU_GITHUB_TOKEN. Options:

Flag
--direct-pushPush approved changes to the target branch instead of opening pull requests.
--push-moru-refsAlso push Moru’s data (refs/moru/) to GitHub.
--publicMake a repository the link creates public. Default: private.
--git-url, --api-urlOverride the git URL (default https://github.com/<github>.git) or the REST API base (default https://api.github.com).

Unlinking makes the node the home of the repository. Repository admins choose Unlink in the bar at the top of the repository. The dialog:

  • lists the changes waiting on GitHub as pull requests. They go back to approved and can be merged on the node. The pull requests stay open on GitHub until someone closes them there;
  • offers to Protect the default branch, ticked by default, so only merging a reviewed change moves it.

After that, the branches no longer update from GitHub, people push to the node, and approved changes merge here. The stored token, if there was one, is removed.

From the command line:

moru-node --data /var/lib/moru unlink-github acme/timetable

It protects the default branch unless you add --no-protect.

Command menu
Search for a page, repository, change or request, or run a command