GitHub
Bring your code to the center of your decision-making with GitHub and DevRev. The GitHub integration allows GitHub users to easily onboard to DevRev and automate day-to-day activities, removing the need for tedious manual tasks.
- Work automation: Connect events in GitHub to your issues in DevRev.
- Magic Commands: Update DevRev issues without leaving your IDE.
- Autotrack work: Automatically track your work in DevRev even without creating an issue ahead of time.
- PR Task Creation: Create DevRev tasks for PR reviewers.
- PR Reminders: Automatically remind PR reviewers when a PR goes stale.
- GitHub issues import: Import issues from your GitHub repositories.
Work Automation
You can enable GitHub work automation via the GitHub for DevRev snap-in by establishing a GitHub connection and setting up a webhook.
To set up GitHub for DevRev snap-in, go to Marketplace and install the GitHub for DevRev snap-in. Follow the instructions for installing the webhook, you can install it for an entire GitHub org or on a per-repository basis.
GitHub Events
Associate GitHub events with DevRev work
You can associate GitHub commits, branches and pull requests with the issues they correspond to. Doing so allows you to see GitHub activity in the corresponding DevRev issue and to act on those events, allowing you to automate away your manual tasks.
Commits
You can associate commits with their corresponding issue by either of these methods:
- Including one or more issue IDs anywhere in the commit message.
- Example:
Fix: paging issue (issue:123) - Example:
Disable routing table ISS-123 and default to zero ISS-231
- Example:
- Including it in a branch that is associated to an issue.
Branches
You can associate a branch with it's corresponding issue(s) by including one or more issue IDs in the branch name. For example, branch mavis/iss-123/teaches-typing. All commits in this branch are automatically associated with issue iss-123, without you having to explicitly include it in the commit message.
Pull Requests
You can track your PRs with the corresponding issues(s) by simply including one or more issue IDs in the PR title. For example, the PR title iss-123 Fixes paging issue links the PR to ISS-123.
Work formats
You can explicitly link an issue ID to a commit, branch or PR by using the following formats:
- Using a display ID:
ISS-123 - Using an issue ID:
issue:123
The display ID and issue ID are case-insensitive, the following are all acceptable and refer to the same issue:
ISSUE:123Issue:123issue:123ISS-123Iss-123iss-123
Automation
After a GitHub event is associated to an issue, the status of that issue is automatically updated according to the following rules:
| GitHub Event | Initial Status | Status | Status Detail |
|---|---|---|---|
| New commit | Open | In Progress | In Development |
| New branch | Open | In Progress | In Development |
| PR Opened | Open | In Progress | In Review |
Magic Commands
With magic commands, you can perform various actions on your DevRev issues without leaving your IDE.
Supported Magic Commands:
Toward
/toward can be used in a PR body to associate a PR with multiple DevRev issues without having to include them in the PR title. This associates the PR with the issues and the automations for stage changes apply just as if the issue IDs had been included in the title.
Example:
Fixes various formatting issues.
/towards ISS-31 ISS-232 ISS-421
Close
/close can be used in a PR body to both associate a PR with multiple DevRev issues and close them when the PR is merged. This associates the PR with the issues and the automations for stage changes apply as soon as the PR is pushed to GitHub. Once the PR is merged, the issues are closed.
Example:
This associates and closes all 3 issues.
Fixes various formatting issues.
/close ISS-31 ISS-232 ISS-421
The special keyword #work can be used to close any issues already associated with a PR without having to specify them, such as when the issue IDs are already in the title.
Fixes various formatting issues.
/close #work
Automatic work detection
DevRev can automatically track your coding activity, even if you don't explicitly associate it with an issue. When you create a new branch or PR, and the branch or PR is not explicitly associated with an issue, DevRev creates an issue for you. We call this an autonomous issue or autonomous work item. DevRev tries to fill in the details for you but you can rename the issue in DevRev, or mark it as belonging to a different, existing issue.
To make use of this feature, the following conditions must be met:
- The DevRev organization has enabled the "Create DevRev issue when a new branch is created" (Preferred) or the "Create DevRev issue when a new PR is opened" feature in the GitHub for DevRev snap-in.
- The "Default part to assign autonomous issues to" has been set to a valid part ID.
- Each developer that wants to use this feature has to link their GitHub account by going to Settings > Account > External Identities and Link GitHub Account.
You can configure these automations from GitHub for DevRev snap-in.
Autonomous work lifecycle
The lifecycle of autonomous work varies from standard work created in DevRev. Certain actions are taken to reduce the burden on developers, including automatically closing the work.
On branch creation
| GitHub Event | Action | Status | Stage |
|---|---|---|---|
| New Branch | Autonomous work created | In Progress | In Development |
| PR Opened | Autonomous work title and description updated with PR details | In Progress | In Review |
| PR Closed | (Default) Closes work if "Close autonomous work on PR merge" is enabled | Closed | Resolved |
| PR Closed | Move back to In Development if "Close autonomous work on PR merge" is disabled | In Progress | In Development |
On PR creation
| GitHub Event | Action | Status | Stage |
|---|---|---|---|
| PR Opened | Autonomous work title and description updated with PR details | In Progress | In Review |
| PR Closed | (Default) Closes work if "Close autonomous work on PR merge" is enabled | Closed | Resolved |
| PR Closed | Move back to In Development if "Close autonomous work on PR merge" is disabled | In Progress | In Development |
Task Creation
DevRev can help you keep track of your issues while they are in the PR process. With PR Task Creation, a task is created for each PR reviewer in the DevRev issue associated with the PR. These tasks are automatically marked as completed when the reviewer approves or denies the PR or when the PR is closed for any reason.
To make use of this feature, the following conditions must be met:
- The DevRev organization has enabled the "Create task for PR reviewers" feature in the GitHub for DevRev snap-in.
- Each developer that wants to use this feature has to link their GitHub account by going to Settings > Account > External Identities and Link GitHub Account.
PR Reminders
PRs can often go stale and delay the development process. With PR reminders, developers can be automatically notified when a PR has been inactive for a configurable period of time.
To make use of this feature, the following conditions must be met:
- The DevRev organization has enabled the "Send reminders for inactive PRs" feature in the GitHub for DevRev snap-in.
- (Optionally) Set the "Number of days to wait before sending PR inactivity reminders".
Issue Import
To ease the transition from GitHub issues to DevRev, you can choose to import GitHub issues into DevRev.
Supported Objects
The following is a list of GitHub objects and their corresponding DevRev equivalent. Those marked as Supported are eligible for import.
| GitHub | DevRev | Supported |
|---|---|---|
| Issue | Issue | ✅ |
| Comment | Comment | ✅ |
| User | DevUsers | ✅ |
| Label | Tag | ✅ |
| Milestone | Tag | ✅ |
| Attachment | Attachment | ❌ |
| Project | Enhancement | ❌ |
Importing from GitHub
Follow the steps below to import from GitHub:
- Go to Settings > Imports and click Start Import or Import.
- Create a new connection to your GitHub account, or use an existing connection if you already have one.
- Once the connection is established, select the GitHub repositories you want to import and specify the DevRev part where the imported issues should be created. This initiates a bulk import of the selected repositories.
- DevRev makes an effort to automatically map the fields from GitHub to corresponding fields in DevRev. However, you may be prompted to manually map certain fields if needed.
The duration of the import depends on the number of issues being imported. It can take seconds for a few dozen issues to hours for tens of thousands of issues with many attachments. DevRev honors the GitHub API rate limits and back-off and resume automatically.
Post import options
After a successful import, you have these options added for each imported repository:
- Sync to DevRev
- This option allows you to synchronize any modifications made in GitHub with the corresponding items previously imported into DevRev. It also creates new items in DevRev for any new issues or users created in GitHub after the last sync or import.
- Periodic Sync
- By enabling this option, you can automatically sync new changes from GitHub to DevRev on a periodic basis. The default frequency is once an hour.
- View Report
- This option allows you to access detailed information about the initial import and any subsequent syncs performed.
- Delete Import
- If you wish to remove the import and all items that were imported from GitHub into DevRev, you can use this option.
- Edit Connection
- Use this option to change the connection used for any subsequent actions. It can be helpful if a connection becomes inactive or the user who established it is no longer available.
GitHub issue import recipe
The following recipe is used to import GitHub issues into DevRev issues.
| GitHub | DevRev | Default Value |
|---|---|---|
| title | title | - |
| body | body | - |
| - | applies_to_part | Selected part |
| assignees* | owned_by | User importing |
| user* | created_by | - |
| user* | modified_by | - |
| created_at | created_date | - |
| updated_at | modified_date | - |
| status | stage | - |
| - | priority | P1 |
| - | work_type | Issue |
| labels | tags | - |
| milestones | tags | - |
* Transient users are created in DevRev for the GitHub assignees and creators.
Historical imports
To view currently running and previous imports from various sources, including GitHub, follow these steps:
- Go to Settings > Imports.
Sync to DevRev
After a successful import from a GitHub repository, you can choose to sync the imported data with DevRev. This feature imports any new issues and any changes made to previously imported issues from GitHub.
To perform a one-time sync to DevRev, follow these steps:
- Go to Settings > Imports.
- Locate the previously imported repository.
- Select the ⇆ > ⇾ From GitHub to DevRev option.
Please be aware that this may override fields in previously imported items, even if they were modified in DevRev.
Periodic Sync
After successfully importing from a GitHub repository, you have the option to enable a periodic sync. This allows for automatic synchronization from GitHub to DevRev on a regular basis. By default, the sync occurs once an hour.
To enable a periodic sync, follow these steps:
- Go to Settings > Imports.
- Locate the previously imported project.
- Select the ⇆ > Start Periodic Sync option.
To disable a periodic sync, follow these steps:
- Go to Settings > Imports.
- Locate the previously imported project.
- Select the ⇆ > Stop Periodic Sync option.