# Epic OP-8237 - Enhanced integration with GitHub pull requests Project: OpenProject Status: closed URL: https://community.openproject.org/work_packages/OP-8237 ## Detailed specification ### Motivation and background information ### Acceptance criteria ### Out of scope | Attribute | Value | | --- | --- | | Mockups | | ## Planning | Attribute | Value | | --- | --- | | Roadmap | | | Date | | | Votes | | | List | | | Target versions | 11.3.0 | | Sprint | 11.3.0 | | Backlog bucket | | | Relevance | | ## Subitems | ID | Type | Subject | Status | Assignee | Target versions | Project | Priority | Spent time | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | OP-8248 | Feature | Link a manually created Pull Request to a work package | closed | | 11.3.0 | OpenProject | Medium | | | OP-8271 | Feature | Implement a new integration system | closed | | 11.3.0 | OpenProject | Medium | | | OP-8276 | Feature | Add new GitHub plugin tab enabling users to copy git actions | closed | | 11.3.0 | OpenProject | Medium | | | OP-8337 | Feature | Copy git commands from the new GitHub work package tab | closed | | 11.3.0 | OpenProject | Medium | | ## Bugs and other work packages | ID | Type | Subject | Status | Assignee | Target versions | Module | | --- | --- | --- | --- | --- | --- | --- | | OP-8667 | Bug | Commands for GitHub integration crammed in German language settings | closed | | 11.3.0 | | | OP-8254 | Task | GH: Calls and Synchronization | closed | | 11.3.0 | | | OP-8253 | Task | GH: Document Use Cases and Vision of the new Integration | closed | | 11.3.0 | | | OP-8252 | Task | GH: Research potential authentication method against GitHub (esp for creating PRs/commits and webhooks/repo-config) | closed | | 11.3.0 | | | OP-8251 | Task | GH: Prototype potential new Github Integration UI | closed | | 11.3.0 | | | OP-8245 | Task | GH: Code Review of the existing GitHub plugin and OP core | closed | | 11.3.0 | | | OP-8341 | Task | GH: Document GitIntegration insights and TODOs before leaving the project | rejected | | 11.3.0 | | ## Details | Attribute | Value | | --- | --- | | Module | | | Enterprise plan | | | Labels | | ## People | Attribute | Value | | --- | --- | | Assignee | | | Accountable | | | Product manager | | | Designer | | | Developers | | | Requested by | | | Interest by | | ## Estimates and progress | Attribute | Value | | --- | --- | | Work | | ## Description # 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. - 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. # 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: Create a linked Pull Request from on a Work Package - 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 menu which eases PR creation - The menu has three options: - commit message: A default commit messages (also used as the default PR description) sourcing its information from the work package `title`, `id`, `url` and `description`. Having that information in the commit/PR helps linking the PR to openproject, as well as giving the full context to GitHub PR reviewers. - branch name: A default branch name sourced from the work package `id` and `title`. Having a default here, helps pairing sessions. It is always clear on which feature branch the work package is developed. - command: Combines the commit messages and branch name from above to a shell-command which creates a new branch with an empty commit containing the defaults. When run from the main branch (e.g. `dev`, `main`, or `master` depending on the project), this helps creating of new PRs by automating repetitive tasks and providing good and consistent defaults. - An example commit message could be: ``` 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. - It is possible to link multiple PRs to a single work package, or have many work packages linked to a single PR ## Use Case 2: Sync progress of a Pull Request with a Work Package - Given there is development progress on a GitHub PR, we want to show it's status on the linked work package - The following GitHub PR states can are synchronized and displayed on the GitHub tab on a work package: - Draft PR is created - A draft PR marked as "ready for review or an already-ready PR was created - A PR was merged - A PR was closed (without merging) - Additional information is shown for each PR within the work packages "GitHub" tab, for example the GitHub account who created the PR # 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