GitHub for DevRev

Sync GitHub and DevRev so issue status is always real time and driven by code.

Overview

Connect GitHub with DevRev, and ensure your work stays in sync between the two systems, such that issues and statuses are always real-time and driven by code activity. GitHub for DevRev is a snap-in that has been used by several organizations, and ties DevRev issues closely with GitHub activity, eliminating the need for humans to manage issues.

Why should you un-manage your work? You should use this snap-in if you want to reduce work about work. Let machines manage issues, including creating and updating statuses, so developers can focus on work that matters. You’ll resonate with this, if you have ever:

Delivered a hot-patch and realized you never had an issue to track it
Wasted time just updating your team on the status of an issue
Or just felt that creating and managing issues is a distraction

If your team’s best practice is to link your GitHub activity to an existing issue-ID during branch creation, commits and PRs, then this snap-in will honor that and enable a GitHub driven issue state, without auto creating issues. Here are the different ways you can link your DevRev issue to GitHub branches, commits and PRs.

However, if you choose to work in GitHub and never created or linked an issue, you shouldn’t have to sweat it. This snap-in will automatically create issues that track all associated commits, branches and pull requests. The auto-created issue is enriched with PR description and related GitHub events. The status of these issues is driven by GitHub activity, and the issues will auto-transition stages, from In Development to In Review, and Closed. Your work is always accounted for and more importantly your team members have visibility and know what you’ve been up to, resulting in fewer interruptions.

How it works

To enable GitHub for DevRev, click on Install and we'll walk you through a few simple steps including connecting with GitHub. You'll have a default set of configuration settings and the option to further personalize this snap-in. Learn more about the features in this snap-in.

Features

This snap-in is powerful, and has several configurable features. As they say, the power is in the defaults! When you install this snap-in, we'll configure defaults that are tried and tested. You always have the option to personalize further.

Automatic status updates

You can associate GitHub commits, branches and pull requests with the DevRev issue 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. Mention DevRev issues in GitHub, and route the relevant GitHub events to this issue. They can be mentioned either as display IDs (ISS-34) or object IDs (issue:34), case insensitively. A DevRev issue can be mentioned in branch names, commit messages or PR titles.

Autocreate issues from GitHub branch

If you do not explicitly associate your DevRev issue to GitHub branches, commits or PRs, then we can autocreate your issues so you have an account of all your GitHub activity. This feature automatically creates an issue when a new branch is created, and tracks all associated commits and Pull Requests on this issue. The auto-created issues will move status based on Git activity, to in development based on branch and commit activity, and in review when PRs are created. When PRs are merged, the issue will be automatically closed, though this behavior is configurable.

Autocreate issues from GitHub PRs

You can choose to automatically create issues when a new PR is created, and it is not linked to an existing DevRev Issue. The behavior is similar to how issues are auto-created with new branches. The auto-created issues will move status based on Git activity, and events are posted on the DevRev issue timeline. It is recommended you enable either one of Autocreate issue from GitHub branch or Autocreate issue from GitHub PR, but not both.

Issues autocreated from GitHub branches or PRs are called autonomous issues, and have the tag autonomous.

Attribute part to autonomous work

Autonomous issues originating from GitHub will be attributed to a default part. You can configure the default part while setting up your snap-in. Every issue in DevRev must have a part attribution.

Enrich autonomous work descriptions

Enrich autonomous issues with information derived from GitHub PR events. The title and description of an autocreated issue is enriched with the PR data. When a new GitHub PR is opened or edited, then the related autonomous issue description is updated with the latest PR description. If the user has removed the auto generated text, then the automation will no longer update the description from PRs. Similarly, autonomous work titles are updated with the PR title, if the user hasn’t already updated it.

Link autonomous work with related issue

Create a related link between the work-items mentioned in the PR body and the autonomous issues tagged with the branch/PR. When a new GitHub PR is opened/edited, for all the autonomous tagged work items(by branch/PR), automatically mark the issues mentioned in the PR as related.

Automatically close autonomous work

Autonomous work gets closed when its related PR is merged. However, if there is no PR activity on this work, then the autonomous work is closed after configurable period.

GitHub Commands

Enable quick actions to close or attribute a PR to DevRev issue(s) with slash command.

/towards - Use the /towards command in the PR description to associate the related GitHub activity to the issue(s). This will ensure that the PR and issue are linked such that related events are posted and issue status is driven by GitHub events.
/close {work-id} - Use /close ISS-3 ISS-4 in a PR body to automatically close a specific issue(s) when the PR is merged. You can also use /close #work to close all associated issues with a PR when that PR is merged without knowing the specific ids.

Automatic PR tasks

When a pull request is requested or reopened, a DevRev task is created for you. In order for this automation to be triggerred, you'll need to link your Pull Requests to DevRev issues. If your PR is removed, merged or closed, then the Task gets deleted. However, if you submit your PR review, then the task is closed.

Automatic PR reminders

When a pull request is inactive for more than a specified number of days, then this automation will post a message in all related DevRev issues. You'll need to link your GitHub Pull Request to DevRev issue to enable these reminders. There are several ways to link your GitHub Pull Requests to DevRev Issues. You can do so by mentioning the DevRev issue-id in Pull Requests title or body, or mention it in the branch name or commit message. Reminders are also posted for issues created autonomously.

You can choose to setup the inactive period in number of days through the max_inactive_days setting.

Frequently asked questions

What is an autonomous issue?

Autonomous issue is an issue created automatically from an external event, such as a new GitHub branch or PR. These issues have the tag autonomous.

How does an issue change status?

	Stage
	From	To
New branch	Any but not closed status	In development
Commit pushed	No change
PR opened	Any but not closed status	In review
PR closed	In review	In development
PR reopened	Any but not closed status	In review
*PR merged (without /close)	In review	In development
PR merged (with /close)	Any but not closed status	Resolved

*This change happens only when change_stage_to_in_development_on_pr_close is true

What are the autonomous work configuration options?

Parameter	Value	Description
`create_work_item_on_new_branch`	Enabled or disabled	Creates autonomous work items on a new branch when no work-id is mentioned
`create_work_item_on_pr_open`	Enabled or disabled	Creates autonomous work items on a new PR, when no work-id is mentioned
`mention_work_directly_in_pr_body`	Enabled or disabled	Link work-id to a PR, when its found in PR body
`enable_magic_commands`	Enabled or disabled	Use magic commands /close and /toward in your PR
`close_autonomous_work_on_merge`	Enabled or disabled	Close the autonomous work when the PR is merged
`default_part`	part display id	Autonomous work is created under this default part
`update_autonomous_work_from_pr`	Enabled or disabled	Enrich autonomous work item title and description with PR data
`link_autonomous_issues_with_pr_mention`	Enabled or disabled	Link the work item mentioned in PR to the autonomous work created
`change_stage_to_in_development_on_pr_close`	Enabled or disabled	Autonomous work changes stage to `in_development` when a PR is closed

How can autonomous work creation be disabled?

You can disable the parameters create_work_item_on_new_branch and create_work_item_on_new_PR to not autocreate issues. If you choose to turn this off as an exception, you can choose to begin your branch name or PR title with nw-(e.g, nw-new-branch)

How can you attribute a part to an autonomous issue?

This automation will infer the part from a repository, if possible. If not, the issue is created with a specified default part.

When is the automous issue closed?

The autonomous work item is automatically closed when its source PR or a PR on its source branch is merged.

What are the prerequisites for scheduling PR reminders?

This automation is triggered when Pull Requests are linked to DevRev issues. If you have not linked GitHub Pull Requests, then reminders will not be posted.

What are the prerequisites for creating PR tasks?

You'll need to connect your GitHub identity with DevRev identity, so we can attribute the tasks to your DevRev user identity. You can link your GitHub identity by going to **Settings > Account > External Identities > Link GitHub Account**..