# User Problem

## User

_What persona, persona segment, or customer type experiences the problem most acutely?_

* Software developer

## Problem

_What problem or job does the user have?_

* Project management, team collaboration, issue tracking and roadmap planning is done in OpenProject, but software development and continuous integration happens on GitHub.
* When pairing/continuing on existing work packages, it is not immediately clear if there is existing work and where to find it on GitHub.
* Commit messages and branch names are inconsistent. There is no guidance/defaults.
* The existing GitHub integration comments on work packages, but gives no good overview (as comments get lost)

## Pain

_What is the primary workaround that users perform that we could remove or replace? Why is it painful?_

* Starting point for a developer is a prioritized and scheduled work package in OpenProject. Before developers can start programming they need to do a lot of manual setup tasks:
* Create PR with reference to work package ID in description.
* Create branch name.
* Provide a PR/commit description, making sure all points from the original work package are covered.
* Begin of the deletion Developers need to manually sync the state of a work package with the the PR progress (`Draft PR created` > `Ready for review` > `closed || merged`). Very often the status is not synced which leads to confusion and errors.
* End of the deletion When teaming up with existing work (taking over a PR or pairing on an existing branch), one has to manually search GitHub for existing PRs or ask the original developer for a branch name. Begin of the deletion
* As an OpenProject administrator, it is hard to set up our current GitHub integration (it requires a "GitHub" user on OpenProject and manually crafted webhooks on GitHub)End of the deletion

# Solution

_How do we solve the user’s problem. What is our “pain killer”? What must we achieve in the first version of the solution in order to achieve value for the user?_

**Summary**: We automate the workflow of synchronizing state between GitHub and OpenProject. At the same time we strive to keep information intended for application-specific use cases in their specific apps. For example, we keep code-review comment in GitHub PRs (not copying them over to OpenProject), and only reference the existence of a PR in OpenProject. At the same time we do not copy OpenProject work package comments over to GitHub.

## Use Case 1: Begin of the insertionCreateEnd of the insertion Begin of the deletion Automatically createEnd of the deletion a linked Pull Request from on a Begin of the insertionWork PackageEnd of the insertion Begin of the deletion work packageEnd of the deletion

* As a developer, I can open a work packages details page to find a new "GitHUb" Tab in the sidebar next to "Activity", "Relations", and "Watchers".
* It is initially empty (as no GitHub PR was linked yet), except for a Begin of the insertionmenu which eases PR creationEnd of the insertion Begin of the deletion "Create PR" button.End of the deletion
* Begin of the insertionThe menu has three options:
* commit message: A default commit messages (also used asEnd of the insertion Begin of the deletion PressingEnd of the deletion the Begin of the insertiondefault PR description) sourcing its information fromEnd of the insertion Begin of the deletion "Create PR" button, automatically creates a new Draft Pull Request onEnd of the deletion the Begin of the insertionwork package `title`, `id`, `url` and `description`. Having that information in the commit/PR helps linking the PREnd of the insertion Begin of the deletion GitHub repository linkedEnd of the deletion to Begin of the insertionopenproject, as well as givingEnd of the insertion the Begin of the insertionfull context to GitHubEnd of the insertion Begin of the deletion project. TheEnd of the deletion PR Begin of the insertionreviewers.
* branch name: A default branch name sourced from the work package `id` and `title`. HavingEnd of the insertion Begin of the deletion containsEnd of the deletion a Begin of the insertiondefault here, helps pairing sessions. It is always clear on which feature branch the work package is developed.
* command: Combines theEnd of the insertion Begin of the deletion newEnd of the deletion commit Begin of the insertionmessages and branch name from above toEnd of the insertion Begin of the deletion withEnd of the deletion a Begin of the insertionshell-command which createsEnd of the insertion Begin of the deletion pre-filled commit message onEnd of the deletion a new Begin of the deletion featureEnd of the deletion branch with an Begin of the insertionemptyEnd of the insertion Begin of the deletion automatically generated name. An example branch name could be `idea/3867-openproject-github-pull-request-integration` with an exampleEnd of the deletion commit Begin of the insertioncontainingEnd of the insertion Begin of the deletion message being:
* End of the deletion the Begin of the insertiondefaults. When run fromEnd of the insertion Begin of the deletion Pull Request containsEnd of the deletion the Begin of the insertionmain branch (e.g. `dev`, `main`, or `master` depending onEnd of the insertion Begin of the deletion same subject and body asEnd of the deletion the Begin of the insertionproject), this helps creating of new PRs by automating repetitive tasks and providing good and consistent defaults.
* An exampleEnd of the insertion commit Begin of the insertionmessage could be:End of the insertion

```text
[#3867] Idea: OpenProject - GitHub Pull Request Integration

[Ticket](https://community.openproject.com/projects/openproject/work_packages/3867)

We want to integrate our pull request workflow with our OpenProject workflow more tightly.

The following features would be nice to have:

* ...
* ...

... (most of the example work package description is intentionally skipped to keep this example small)
```

* The "GitHub" sidebar automatically lists the newly created PR with a link to its GitHub page.
* Begin of the insertionItEnd of the insertion Begin of the deletion optional: An additional buttonEnd of the deletion is Begin of the insertionpossible to link multiple PRs toEnd of the insertion Begin of the deletion show which copiesEnd of the deletion a Begin of the insertionsingle work package, or have many work packages linkedEnd of the insertion Begin of the deletion "git checkout" command (`git fetch && git checkout idea/3867-openproject-github-pull-request-integration`)End of the deletion to Begin of the insertiona single PREnd of the insertion Begin of the deletion the users clipboard.End of the deletion

## Use Case 2: Sync progress of a Pull Request with Begin of the insertiona Work PackageEnd of the insertion Begin of the deletion work packageEnd of the deletion

* Given there is development progress on a Begin of the insertionGitHubEnd of the insertion PR, Begin of the insertionwe want to show it'sEnd of the insertion status Begin of the deletion transitions can be configuredEnd of the deletion on Begin of the deletion a per-project basis that are applied toEnd of the deletion the linked work package
* The following GitHub Begin of the insertionPR statesEnd of the insertion Begin of the deletion actionsEnd of the deletion can Begin of the insertionare synchronized and displayed on the GitHub tab on a work package:End of the insertion Begin of the deletion be configured:End of the deletion
* Draft PR is Begin of the insertioncreated
* A draft PREnd of the insertion marked as "ready for Begin of the insertionreview or an already-ready PR was createdEnd of the insertion Begin of the deletion review"End of the deletion
* A PR was merged
* A PR was closed Begin of the insertion(without merging)End of the insertion Begin of the deletion without mergingEnd of the deletion
* Begin of the insertionAdditional information is shown for eachEnd of the insertion Begin of the deletion The OpenProject "development" sidebar shows the current status of any linkedEnd of the deletion PR Begin of the insertionwithinEnd of the insertion Begin of the deletion (draft, open, closed, merged) along withEnd of the deletion the Begin of the deletion GitHub user who created the PR.

## Use Case 3: Link a manually created Pull Request to aEnd of the deletion work Begin of the insertionpackages "GitHub" tab,End of the insertion Begin of the deletion package

* It is possible to link PRs to a work package without using the "Create PR" button mentioned before by mentioning the ticket-code in brackets in a PR subject, a PR body, or a commit message. The work package codeEnd of the deletion for Begin of the insertionexampleEnd of the insertion Begin of the deletion a work package withEnd of the deletion the Begin of the deletion ID 3867 is `[#3867]`.
* Using this method, it is possible to link multiple PRs to a single work package.

## Use Case 4: Set-Up a new project withEnd of the deletion GitHub Begin of the insertionaccount who createdEnd of the insertion Begin of the deletion integration

* We add a new instance-wide configuration setting to authenticateEnd of the deletion the Begin of the deletion OpenProject instance against a GitHub organization or user, using the ["GitHub App OAuth flow"](https://docs.github.com/en/developers/apps/authorizing-oauth-apps).
* We add new configuration which allows to select a GitHub repository from a list of repositories OpenProject has access to using the GitHub App mentioned above.
* This page also allows to configure state transitions onEnd of the deletion PR Begin of the deletion updates, see: "Use Case: Progress on a Pull Request".End of the deletion

Begin of the deletion ## Use Case 5: Create links to OpenProject work packages in PR descriptions

* When a PR is created, edited or a new comment was added on GitHub, OpenProject scans the text for work package codes (e.g. `[#3867]`) and replaces these with links to the respective work package.
* This assumes a project is linked to the repository and the project has a work package with the mentioned ID.

End of the deletion # Out of Scope for the MVC

_What should NOT be in the minimal viable change, and can be considered for future iterations? Why? Please order them by importance._

* Please see ##36207 for further ideas Begin of the deletion

# (Technical) Considerations

* We need to add support for the official GitHub API using GitHub Apps and the OAuth flow as webhooks alone don't allow us to create commits/PRs
* Optionally we could use [a solution like tickety-tick](https://github.com/bitcrowd/tickety-tick/) which copies a shell-command to create the branch/commit to the users clipboard.
* We could continue to use work package comments as the means of communication to save development time, but this would likely reduce the perceived customer value (less overview of the current state on GitHub).
* In this proposal the "development" sidebar is imagined to be part of OpenProject core (enabled with a project-option). This sidebar is filled by plugins for GitHub, and later, GitLab.
* This allows us to provide a core-infrastructure for development information and only specialize in the GitHub/GitLab-specific parts.
* Potentially, our existing Git integration could use the same sidebar.
* Potentially, we could integrate all sorts of app in that toolbar (e.g. CAT programs, other editors where "the real work" is done) and link items to WP's)
* A preliminary data model for the GitHub integration

# UI Prototypes

The following figma link contains some early UI prototypes. They are likely to need further discussion and grooming.

[https://www.figma.com/file/nOA3zyuP4FcARe4GJac0xQ/OP-GH-Integration?node-id=0%3A1](https://www.figma.com/file/nOA3zyuP4FcARe4GJac0xQ/OP-GH-Integration?node-id=0%3A1)End of the deletion