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 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 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 ProgressIn Development
    New branchOpenIn ProgressIn Development
    PR OpenedOpenIn ProgressIn Review

    Automatic work detection#

    DevRev can automatically track your coding activity, even if you don't explicitly associate it with a work item. When you create a new branch or PR, and the branch or PR 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 in the GitHub for DevRev snap-in
    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 GitHub for DevRev snap-in.

    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, go 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
    • View Report
      • View details of the initial import and any syncs performed afterward
    • Delete Import
      • Removes the import and all work that was imported into DevRev from the GitHub repository
    • Edit Connection
      • Changes the connection used for any subsequent action (i.e. Sync). This is helpful if a connection goes stale 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 work.

    GitHubDevRevDefault Value
    titletitle-
    bodybody-
    -applies_to_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.