Chrome extension

The Chrome extension shows your practice review on the GitHub or GitLab page of the work you view. It links to the comments posted for you, lists your observations, and shows when the work was last reviewed. You read the feedback itself in the comment, on your Practice profile, or with Hephaestus.

What you need

• Chrome on a desktop computer. Chrome on Android and iOS cannot run desktop extensions. Other browsers are not supported.
• A Hephaestus account on an instance that allows the extension.
• Membership in a workspace that monitors the repository you view.

The extension is not in the Chrome Web Store. Your organization’s Chrome settings may install it for you. Otherwise, install it from the package of a Hephaestus release.

Install it

If the Hephaestus icon is already in Chrome’s puzzle-piece menu, your organization installed it for you. Go to Connect it to your Hephaestus.

1. Get hephaestus-chrome-extension-X.Y.Z.zip from your Hephaestus admins. They check that the release signed it.
2. Unzip it into a folder that you keep. Chrome runs the extension from that folder, so do not move or delete it.
3. Open chrome://extensions and turn on Developer mode.
4. Select Load unpacked and choose the folder.
5. Copy the ID that Chrome shows under Hephaestus, and send it to your admins. Your instance accepts sign-in only from an ID that its admins allow.

Chrome labels the extension as unpacked, and it does not update itself. To update it, replace the folder’s contents with a newer package. Then select the reload button under Hephaestus on chrome://extensions. The ID stays the same while the folder stays in the same place.

Connect it to your Hephaestus

1. If you cannot see the Hephaestus icon, pin it from Chrome’s puzzle-piece menu.
2. Select the Hephaestus toolbar icon to open extension settings.
3. For hephaestus.build, select Connect to Hephaestus. For another instance, go to the next step.
4. Open Use a self-hosted instance, enter its HTTPS address, and select Connect instance.
5. Allow Chrome’s request for access to that address.
6. Select the sign-in button for your usual provider, such as Sign in with GitHub.

The sign-in window opens on your Hephaestus and sends you on to GitHub or GitLab, as the web app does. It uses your normal Chrome profile, so you may not need to sign in to the provider again. After sign-in, the window closes, and settings show who you’re signed in as. If you close the window before you finish, nothing changes, and you can try again.

You can also paste a workspace address of a self-hosted instance. The extension finds the instance address in it and asks you to connect there. You can change the instance later on the same page.

Allow it on GitHub and GitLab

The extension reads nothing on a site until you allow it. Settings list the sites connected to your workspaces: github.com, gitlab.com, or your organization’s GitLab address. Each site needs its own permission, and Chrome asks each time.

1. In extension settings, select Allow beside each site you need.

Each pull request, merge request, or issue that you then open on that site shows its review line. To stop the extension on a site, select Remove beside it, or remove the site in Chrome’s extension settings.

Read the review of a work page

1. Open a pull request, merge request, or issue on an allowed site.
2. Select the review line to expand the report in place.
3. Select it again to close the report.

The page moves down to make room for the report. The report stays open while you stay on the same work in that tab, also when you switch to the changes and back.

The review line

The review line sits in the page’s content column, after the description or above the changed files. It shows, in order:

1. Review waiting or Review running, while a review of the work is in progress.
2. The number of comments Hephaestus recorded as posted for you on this work.
3. The latest review time, or review status unavailable when your account has no review history for this work.
4. review partial or review failed, if the latest review did not finish.

For example: 3 comments for you · reviewed 2 hr. ago.

No recorded comments for you means only that Hephaestus recorded no comment for you on this work. It is not a clean result. The work may be unreviewed, or no practice may check what happened. review status unavailable does not mean that nobody reviewed the work.

The report

• Your comments. Each row is a comment that Hephaestus posted for you on this work. The row links to the comment on the page and shows its practices and delivery time. To respond to the feedback, follow the Hephaestus link in the comment.
• Your observations. Each row names the practice, the outcome, the severity for Not met, and a one-sentence summary. A Not met row lists its problems, one line each. The first five rows appear, and Show … more shows the rest.
• When, and where to read more. The exact time of the latest review, and its commit if known.

The comment list shows what Hephaestus recorded when it posted. Someone may have changed or deleted a comment since then.

Open in Hephaestus opens your feedback and observations on the work in the web app, on Your feedback on this work. That page also shows each earlier review of the work.

Workspace admins also get Review details. It opens the web app with every developer’s observations, the delivery state of each piece of feedback, and each review.

Preview work from a list

On GitHub and GitLab lists of pull requests, merge requests, issues, or work items, each row has a small Hephaestus button after its title. Nothing is looked up until you select one.

1. Select a row’s Hephaestus button. One line from the work’s report appears below the row title.
2. To open the full report, select the row’s title.

Only one preview is open at a time. The same button, a list filter, or a page change closes it.

Request a review

Request review appears on the work page if you are the author, an assignee, or a workspace admin. It appears only when no review of that work is waiting or running.

1. On the work page, select Request review.
2. Check the work and workspace named in the confirmation window.
3. Select Request review in that window.

The page cannot cover or read that window, and the extension sends nothing before you confirm. If Hephaestus does not start a review, the window shows the reason. If no answer arrives, the window says that the request may or may not have gone through, and it does not retry. Check the review line before you ask again.

A review request is the only change that you can make from the page. You cancel a review, retry its observations, and approve or reject feedback in the web app, through Review details.

Stay signed in or sign out

You stay signed in until you close Chrome or seven days pass, whichever comes first. Your instance may set a shorter limit. In Hephaestus, User settings lists the session as Browser extension in Chrome on ….

To sign out, select Sign out in extension settings. Ending the session in User settings also signs the extension out. Signing out, or changing the Hephaestus address, clears the extension’s content from every tab.

Privacy

The extension sends Hephaestus the address of each work page that you open on an allowed site, and of each list row that you preview. It reads no page text. Chrome extension privacy lists what it reads, sends, and stores.

Troubleshooting

This server is too old for this extension

The extension can be newer than your Hephaestus server, for example when your organization installs a newer package. Ask your instance operator to upgrade the server. The report works again after that, and you do not need to reinstall.

This instance does not know this extension

The instance does not allow the extension. Ask its operators to allow it. If you installed it yourself, send them the ID that Chrome shows on chrome://extensions.

No GitHub or GitLab site to allow yet

You do not belong to a workspace that is connected to GitHub or GitLab. Select Open Hephaestus to see your workspaces, or ask to join one.

One step left in Hephaestus

Your account needs a step in the web app, such as acceptance of the current notice.

1. Select Open Hephaestus.
2. Finish the step shown.
3. Return to extension settings, and select Check again.

We could not load here

The report did not start.

1. Reload the page.
2. If the problem continues, open settings from the toolbar icon.
3. Check that you are signed in.

We could not load

Your Hephaestus did not answer. Check your connection, then select Retry.

We could not load your comments

The report loaded, but your comments did not. Open the report, then select Retry.

Connect the extension to Hephaestus

The extension is not connected to an instance. Select Set up.

Sign in to … to see it

Your sign-in ended. Select Sign in.

Not available for this work

No workspace connects to this site, or the work is not in a workspace that you can open. On a page that is not a single pull request, merge request, or issue, the report asks you to open one. Open the report. It gives the reason if it can tell.

Followed in 2 workspaces

More than one workspace follows this work. Open the report, then choose a workspace.

Not refreshed

Hephaestus did not answer the latest refresh. The report shows its last answer and that answer’s time. In a list preview, select Retry.