GitHub

Bring your code to the center of your decision-making with GitHub and DevRev. The GitHub integration allows GitHub users to onboard to DevRev and automate day-to-day activities, removing the need for tedious manual tasks.

• Work automation: Connect GitHub events to your DevRev issues.
• 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 through the GitHub for DevRev snap-in by establishing a GitHub connection and setting up a webhook.

To set up the GitHub for DevRev snap-in, go to Marketplace and install the GitHub for DevRev snap-in.

Webhook installation

During the snap-in installation, follow the instructions for installing the webhook. The webhook can be installed for an entire GitHub org or specific repositories. If you install the webhook successfully, the message "Webhook installed successfully" is displayed in the Discussions tab. If it was not installed correctly, you can see "Webhook installation is unsuccessful". If the webhook is not successfully installed, you need to create the webhook manually by following the instructions below.

1. Go to Settings > Webhooks in your GitHub organization or repository and select Add webhook.

2. Add the following in the Payload URL field:

   1 https://api.dev.devrev-eng.ai/hidden/dev-orgs/DEV-787/event-source-webhooks/github/2ce09ba6-1d08-4cb6-ac0b-e0b2169aa18c
   

3. Set Content type to application/json.

4. Add the following secret:

   1 dsnYinUbUK2U7ea3Ym1PlVxywHZ28B`
   2 
   

5. In Events, select Let me select individual events. Select the following events:

   a. Branch or tag creation

   b. Pushes

   c. Pull requests

   d. Pull request review comments

   e. Pull request review threads

   f. Pull request reviews

6. Finalize the creation by clicking Add webhook in GitHub and closing this window.

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 your manual tasks.

Commits

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

1. 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
2. Including it in a branch that's associated with an issue.

Branches

You can associate a branch with its corresponding issues 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 by 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:

1. Using a display ID: ISS-123
2. 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:123
• Issue:123
• issue:123
• ISS-123
• Iss-123
• iss-123

Automation

After a GitHub event is associated with an issue, the status of that issue is automatically updated according to the following rules:

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:

1 Fixes various formatting issues.
2 /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. If the command is not included, the issue stage will move from In Review to In Development, instead of transitioning to the closed state.

Example:

This associates and closes all 3 issues.

1 Fixes various formatting issues.
2 /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.

1 Fixes various formatting issues.
2 /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 isn't 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, go to My settings and toggle Enable for me.

1. You can enable the "Create DevRev issue when a new branch is created" or the Create DevRev issue when a new PR is opened feature in the GitHub for DevRev snap-in.
2. The "Default part to assign autonomous issues to" has been set to a valid part ID.
3. 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

On PR creation

Task creation

DevRev can help you keep track of your issues while they're 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:

1. The DevRev organization has enabled the Create task for PR reviewers feature in the GitHub for DevRev snap-in.
2. 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 period of time.

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

1. The DevRev organization has enabled the "Send reminders for inactive PRs" feature in the GitHub for DevRev snap-in.
2. (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.

Importing from GitHub

Follow the steps below to import from GitHub:

For best results, imports should be done using an administrator account on the external source. This ensures all necessary permissions are available to complete the import successfully.

1. Go to Settings > Integrations > Imports and click Start Import or Import.
2. Create a new connection to your GitHub account, or use an existing connection if you already have one.
3. 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.
4. 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, it backs off and resumes 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 periodically. 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.

Transient users are created in DevRev for the GitHub assignees and creators.

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:

1. Go to Settings > Integrations > Imports.
2. Locate the previously imported repository.
3. 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.

Historical imports

To view currently running and previous imports from various sources, do the following:

1. Go to Settings > Integrations > Imports.
2. Select the import you want to view.
3. Click on the context menu (⋮) and select View Report.

Periodic sync

After successfully importing to DevRev, you have the option to enable a periodic sync. This allows for automatic synchronization with DevRev on a regular basis. By default, the sync occurs once an hour.

To configure periodic sync, follow these steps:

1. Go to Settings > Integrations > Imports.
2. Locate the previously imported project.
3. Select the ⇆ > Set Periodic Sync option.

The Enable automations for synced items setting is optional and can be activated during periodic sync configuration. When enabled, newly created or updated items trigger events, which can initiate webhooks, notifications, Snap-ins, and other processes, as if the events originated directly in DevRev.

If this setting is disabled, updates will not trigger any event-driven processes. This behavior applies only to periodic syncs; no events are triggered during a first-time import or manual sync to or from DevRev.

Delete import

This deletes any content created by the import, including users and works.

An import and all the content it creates can be deleted from DevRev. This can be useful when running POCs or to change the recipe used during the import. Once an import has been deleted, all the content it created gets deleted, even if they were modified in DevRev. It's possible to import the project again after its deletion.

To delete an import and all the content it created, go to Settings > Integrations > Imports, find the previously imported project, and select ⋮ > Delete Import.