Install with GitHub
Learn how Volta synchronizes your repositories with GitHub.
Overview
Volta is built on top of GitHub API to provide a new way to work on top of your repositories and issues. To achieve this first-class integration, we leverage the power of GitHub Apps.
Installation
To get started, you need to install our GitHub app in your personal account or in the organizations you own. To install a GitHub App, you must be an organization owner or have admin permissions in a repository, otherwise one will need to approve the request.
You can access the installation page from anywhere in the app by clicking on Install with GitHub.
Permissions
When installing our GitHub app, you will be prompted to accept some permissions:
- Read access to
actions,code,membersandmetadata - Read and write access to
issuesandpull requests
These permissions are required to provide a seamless experience when working with your repositories and issues:
We need read access to actions to send a notification when a workflow run fails on a pull request or on the repository default branch, metadata is mandatory to fetch repository data, members to import your organization members and repository collaborators.
The code access is part of the Contents permission that includes repository contents, commits, branches, downloads, releases and merges. We only use this permission to read commits, tags and releases. We do not read or write any code to your repositories. We only parse the content of commits to display in issue activity and to automate issue boards without storing any code.
Volta acts on your behalf to manage issues and pull requests with related comments, assignees, reviewers and labels. We need read and write access to issues and pull requests to do so.
Repositories
When installing our GitHub app, you will be prompted to select all repositories or a subset of them. This selection can be changed at any time by going to the GitHub app settings.
By clicking on Install, Volta will start importing all the repositories you selected.
Import process
Repositories (except forks that are ignored) will be imported in background. When importing a repository we have to fetch all collaborators, issues, pull requests, comments, reactions, labels... This requires a tremendous amount of http calls to the GitHub API and can take a while depending on the number of selected repositories.
Also, GitHub apps are rate limited to 15,000 requests per hour per organization. To solve this issue, we use a queue to import repositories one by one with a retry system in case of rate limit exceeded.
This process is only done once and then everything is kept up-to-date through webhooks.
Collaborators
The first thing we do is to import the collaborators of the repository with their permissions. As Volta is first and foremost made for maintainers, this allows us to attach users to repositories they have access to, only users with triage, maintain, write or admin permission will be considered as maintainer.
As a maintainer, you will see your repositories grouped by organization in the sidebar and will be automatically subscribed to the repository notifications. As everything is kept in sync with GitHub, if you change user's permissions in an organization or repository, it will be passed on to Volta.
This especially allows us to restrict access to private repositories. Public repositories are still accessible even if you're not considered a maintainer through search and navigation.
Even if you've never logged in to Volta, you might be considered as a maintainer, that's why when you first log in you might see your repositories if someone already installed the GitHub app on one of your organization.
When importing a repository for the first time, all maintainers will be automatically subscribed asWatch.Issues / Pull Requests
As Volta main purpose is to provide an issue board for repositories out of the box, we need to import all issues and pull requests.
Open issues will be added to the Triage column, except for issues that are linked to open pull requests, those will be added to the In Progress or In Review column depending on the pull request state. Issues closed prior to the import will not be displayed in the board or list but only available to reference, search or navigate.
We also import all related comments, reactions, assignees, reviewers and labels to provide a full experience.
When importing a repository for the first time, Volta will automatically subscribe users that have commented, assigned or requested as reviewer on the issue.Releases
Releases are imported to notify users that have subscribed to this repository with the or preset. They will receive a notification when a new release is published, which will be displayed in the inbox preview.
Tags
Tags are imported to be attached to issues and pull requests.
Also, when a new tag is pushed to your repository, all issues in Done status will be automatically moved to Released status and linked to the tag.Commits
We do not fetch commits during the import process. However, we store newest commits on pull requests through webhooks to display in the activity and to provide additional features.
For example, when a commit message contains a closing keyword (e.g.Fixes #10), the issue will be moved to Done.Actions
We do not fetch actions during the import process. However, we store newest actions on pull requests through webhooks to display commits checks in the activity and to provide additional features.
For example, you will receive a notification when a workflow run fails.Uninstall
You can delete your account along with all of its settings, favorites and notifications. To do so, open the global settings modal by pressing ,, then under click button.
All your data imported from GitHub is directly tied to your GitHub app installation.
If you want a complete deletion of your repositories, issues and their related data, please uninstall our GitHub app from your organizations.