Visual chrome for using Bors' Github integration with the Chrome Browser
Replace the existing merge options on a Github Pull Request with a button that comments on the Pull Request with "bors r+"
- Clone the repo and run
yarn installto fetch the dependencies - Build the extension locally with
yarn buildto generate the output files in a format Chrome will accept - Load the unpacked extension from the
/builddirectory in the repository - Change the code, run
yarn buildand reload the extension, to see the changes in action!
Chrome has a standard set of architecture patterns it recommends for all extensions (at least until the Manifest V3 changes roll out!). This involves a few different moving parts which communicate via message passing. Let's break this down by section and discuss each one and how they fit together to protect our repos from dastardly merges.
The content script alters the Github page for any repos protected by Bors Armor. The manifest.json file sets the content script to run on document_end. The content script first checks if it should run, and if so does the following:
- Identify the merge panel, which is where Github stores most metadata and actions related to merging a Pull Request into the base branch (generally "master")
- Copy an existing "merge-status" item for one of the supported merge strategies on Github (merge, squash, rebase) and replace it with Bors-specific language, hiding other strategies
- Copy an existing "merge-button" item for one of the supported merge strategies on Github (merge, squash, rebase) and replace it with Bors-specific language, hiding other strategies. This is where the majority of the UI logic lives. When creating the Bors button for use in the Github UI, the existing Github status checks are used to determine whether the button should be disabled or not.
- Copy an existing "button group" for one of the supported merge strategies on Github (merge, squash, rebase) and replace it with Bors-specific language, hiding other strategies
The strategy of copying existing UI elements used for other merge strategies rather than building new elements from scratch for Bors Armor is intended to be robust against Github UI changes, since that's out of the control of this extension.
The popup is a browser_action that initially checks whether the current URL is protected and alters it's own UI to reflect the current state of the repository being viewed. Once the initial state has been set it allows either activating or deactivating a Github repository by sending a message to the background page to alter the list of stored repository URLs. It then optimistically updates the popup UI.
The background page essentially functions as a primitive service worker. The background page is intended to tie together functionality across the various user-visible parts of the Chrome extension and within the content script. However, Bors Armor was initially developed as a single content script that ran on every Github repository and then was refactored heavily to use the background page and popup systems common in Chrome extensions. With additional work the background page could probably be used more effectively to direct when the content script runs and ensure Bors Armor remains active even when Github refreshes their UI in the background.
As it stands the background page is responsible for various disparate functionality:
- Initialize the storage for Bors Armor. By default, the Bors Armor repository is protected.
- Set the Page Action to active for Github URLs
- Listen for messages from the popup adding/removing Github repositories
- Respond to the content script when it attempts to run for a specific browser tab
In developing Bors Armor, three distinct Github Pull Request UIs need to be taken into account
- A repo without any status checks enabled
- A repo with non-Bors status checks enabled
- A repo with Bors enabled as a status check (Bors' status check remains in a pending state until after it first attempts a merge)
To package Bors Armor for distribution run yarn zip and upload the bors-armor.zip output file to the Chorme Web Store.
Current icon Armor by lastspark from the Noun Project