GitHub Integration

Overview#

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.

Feature Overview

Work Automation#

You can enable GitHub work automation via DevRev's Flows by establishing a GitHub connection and setting up a webhook.

To set up GitHub work automation, go to DevOrg Settings > Connections and select an existing GitHub connection or create a new one. Under the GitHub connection, select GitHub Events, configure the settings and select Next. 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 work they correspond to. Doing so allows you to see GitHub activity in the corresponding DevRev work and to act on those events, allowing you to automate away your manual tasks.

Commits

You can associate commits with their corresponding work by either of these methods:

  1. Including one or more work ids anywhere in the commit message
    • Example: Fix: paging issue (issue:123)
    • Example: Disable routing table ISS-123 and default to zero ISS-231
  2. Including it in a branch that is associated to a work item

Branches

You can associate a branch with its corresponding work item(s) by including one or more work ids in the branch name. For example, branch mavis/iss-123/teaches-typing. All commits in this branch will then also be automatically associated with work item iss-123, without you having to explicitly include it in the commit message.

Pull Requests

You can track your PRs with the corresponding work item(s) by simply including one or more work ids in the PR title. For example, the PR title tkt-123 Fixes paging issue will link the PR to tkt-123.

Work formats#

You can explicitly link a work id to a commit, branch or PR by using the following formats:

  1. Using a display id: ISS-123, tkt-123, iss-123
  2. Using a work id: issue:123, ticket:123

The display id and work id are case insensitive, the following are all acceptable and refer to the same work item:

  • ISSUE:123
  • Issue:123
  • issue:123
  • ISS-123
  • Iss-123
  • iss-123

Automation#

After a GitHub event is associated to a work item, the status of that work item is automatically updated according to the following rules:

GitHub EventInitial StatusStatusStatus Detail
New commitOpenIn ProgressCoding
New branchOpenIn ProgressCoding
PR OpenedOpenIn ProgressIn Review
PR mergedOpenClosed-
PR mergedIn ProgressClosed-

Automatic work detection#

DevRev can automatically track your coding activity, even if you don't explicitly associate it with with a work item. When you create a new branch, and the branch is not explicitly associated with a work item, DevRev will create a work item for you. You can later rename the work item in DevRev, or mark it as belonging to a different, existing work item.

To make use of this feature, the following conditions must be met:

  1. The DevRev organization has enabled the "New Branch Work Creation" feature under a GitHub connection
  2. You must link your GitHub account by going to DevOrg Settings > Account > External Identities and Link GitHub Account

You can configure these automations from the DevOrg Settings > Connections and selecting a GitHub connection.

Issue Import#

To ease the transition from GitHub issues to DevRev, you can choose to import GitHub issues into DevRev. To migrate GitHub issues from one or more repositories, navigate to DevOrg Settings > Imports then select Start Import or Import.

From there, create a new connection to a GitHub organization or use an existing connection if you already have one. Once the connection is established, select the repositories you wish to import. This will perform a bulk import of the selected repositories.

Post import options

After a successful import, you will have these options added for each imported repository:

  • Sync to DevRev
    • Write any modifications made in GitHub issues to the corresponding work item in DevRev
    • Create new work items in DevRev for any new issues created in the GitHub repository after the last sync or import

GitHub issue import recipe#

The following recipe is used to import GitHub issues into DevRev work:

GitHubDevRevDefault Value
titletitle-
bodybody-
-primary_part_idSelected part
assignees*owned_by_idsUser importing
user*created_by_id-
user*modified_by_id-
created_atcreated_date-
updated_atmodified_date-
statusstatus-
-priorityP1
-work_typeIssue
-channelWeb
due_ondue_on-
labelstags-
milestonestags-

*Transient users will be created in DevRev for the GitHub assignees and creators.

Historical imports#

You can view currently running and previous imports from any source, including GitHub, by navigating to DevOrg Settings > Imports.

Sync to DevRev#

After a successful issue import from a GitHub repository, you have the Sync to DevRev option. The Sync to DevRev feature will import any new issues and any new changes to previously imported issues.

To perform a sync to DevRev, go to DevOrg Settings > Imports, find the previously imported repository and select the Sync > -> DevRev option.

*Note: This will override work's fields, even if they were changed in DevRev.