Rebecca GitHub integration (#9354)

* GitHub integration how to

new screenshots and first steps
[ci skip]

* GitHub integration explanation

Added description how the new GitHub integration works including step by step screenshots
[ci skip]

Author: RBernsen

docs/system-admin-guide/github-integration/GitHub-action.png

@@ -8,34 +8,9 @@ keywords: github integration
 ---
 # GitHub integration
 
-OpenProject offers an integration for GitHub pull requests.
-You create a pull request in GitHub and link it to an OpenProject work package.
+OpenProject offers an integration for GitHub pull requests to integrate software development closely with planning and specification.
 
-![New pull request linking to an OpenProject work package](github-pr-workpackage-reference.png)
-
-Rather than inserting a link to the work package you can also reference it just by adding "OP#87" to the pull request's description where 87 is the ID of the work package.
-
-OpenProject will add comments to work packages about the pull request when the pull request is
-
-* first referenced (usually when opened)
-* merged
-* closed
-
-![Github comments on work package](workpackage-github-comments.png)
-
-Given the right permissions on the project, a "GitHub" tab is shown for work packages. All previously linked pull requests can be seen there including the PR's status and checks (e.g. tests and linter runs).
-
-## Configuration
-
-You will have to configure both OpenProject and GitHub for the integration to work.
-
-### OpenProject
-
-In *Project settings* and *Modules* you will need to activate the GitHub module.
-
-![Github-module](Github-module.png)
-
-Then you will have a GitHub tab appearing in your work package view where you will see all information pulling through from GitHub.
+OpenProject work packages will directly display information from GitHub in a separate tab.
 
 ![GitHub-tab](GitHub-tab.png)
 
@@ -44,59 +19,61 @@ In your OpenProject work package, the GitHub integration supports you to create
 
 ![GitHub-create-branch](GitHub-create-branch.png)
 
+In order to create a new branch, open the GitHub tab in your OpenProject work package detail view. Click on Git snippets to extend the menu. First, copy the branch name.
 
+![GitHub-copy-branch-name](GitHub-copy-branch-name.png)
 
-Copy Branch name
+Then, open your desktop client, e.g. GitHub desktop. There, you create your branch with the name you copied from your OpenProject work package.
 
-Then open new branch in GitHub desktop
+![GitHub-desktop-new-branch](GitHub-desktop-new-branch.png)
 
-Then go to Typora and make changes
+Then go to Typora (or any other editor) and create content or make changes.
 
-Save
+![GitHub-test-copy](GitHub-test-copy.png)
 
-Changes in GitHub desktop
+Save and the changes will appear in GitHub desktop or the client you are using.
 
-in OP use commit message
+![GitHub-changes](GitHub-changes.png)
 
-Publish branch
+In order to commit these changes, go to OpenProject to copy the commit message.
 
+![GitHub_OpenProject-commit-message](GitHub_OpenProject-commit-message.png)
 
+And use it in the GitHub desktop commmit message field. Make sure you use the reference for the OpenProject work package (in this case #6006) in the title.
 
+![GitHub-commit](GitHub-commit-2645308.png)
 
+After having committed, publish your branch.
 
-create PR
+![GitHub-publish-branch](GitHub-publish-branch.png)
 
-add info in comment
+Subsequently, you can create your pull request. Title and comment with the link to the respective OpenProject work package will be prefilled. If you want, you can add some additional information.
 
-create PR green button
+![GitHub-open-pull-request](GitHub-open-pull-request-2645707.png)
 
-click link to OP WP
+Click on **Create pull request** and your pull request will be opened.
 
-comment in activity that PR is created
+![GitHub-pull-request-opened](GitHub-pull-request-opened-2646257.png)
 
-commit messaage mit OP Verweis auf das AP
+When you click on the link in the comment, it will take you to the OpenProject work package, where you will see in the Activity tab of the work package that the pull request was created.
 
+![GitHub-work-package-activity](GitHub-work-package-activity-2646492.png)
 
+In the GitHub tab of that work package, the status of the pull request as well as the GitHub Action will be displayed.
 
-see GitHub action in GitHub tab
+![GitHub-action](GitHub-action.png)
 
-
-
-If PR is merged, it will appear in OP
-
-
-
-If you already have an existing pull request in GitHub, you can link it using the code OP#0000 (0000 being the ID of the work package) in the GitHub pull request description.
-
-
-
-![GitHub-actions](GitHub-actions.png)
+If the status of a pull request changes, it will accordingly appear in its OpenProject work package. Please see the example below.
 
 ![GitHub-pull-request-status](GitHub-pull-request-status.png)
 
 
 
+## Configuration
 
+You will have to configure both OpenProject and GitHub for the integration to work.
+
+### OpenProject
 
 First you will need to create a user in OpenProject that will make the comments.
 The user will have to be added to each project with a role that allows them
@@ -116,7 +93,11 @@ to use later on the GitHub side of things. For this you have to:
 3. Go to Access Token
 4. Click on generate in the API row
 
-Copy the generated key. You can now configure the necessary webhook in GitHub.
+Copy the generated key. You can then configure the necessary webhook in GitHub.
+
+In addition, in *Project settings* and *Modules* you will need to activate the GitHub module so that all information pulling through from GitHub will be shown in the work packages.
+
+![Github-module](Github-module-2647262.png)
 
 ### GitHub