[#62067] Update GitHub and GitLab documentation for coders https://c… (#18448)

* [#62067] Update GitHub and GitLab documentation for coders  https://community.openproject.org/work_packages/62067

[#62067] Update GitHub and GitLab documentation for coders

https://community.openproject.org/work_packages/62067

* Apply suggestions from code review

Co-authored-by: Kabiru Mwenja <k.mwenja@openproject.com>

* improve images

* updating github documentation

* Update docs/system-admin-guide/integrations/github-integration/README.md

---------

Co-authored-by: Kabiru Mwenja <k.mwenja@openproject.com>

docs/system-admin-guide/integrations/github-integration/README.md

@@ -7,94 +7,41 @@ keywords: github integration
 ---
 # GitHub integration
 
-OpenProject offers an integration with GitHub pull requests (PRs) to link software development closely to planning and specification.
-You create a pull request in GitHub and link it to an OpenProject work package.
+OpenProject offers an integration with GitHub pull requests (PRs) to link software development closely to planning and specification. You can create pull requests in GitHub and link them directly to OpenProject work packages.
 
 ## Overview
 
 OpenProject work packages will directly display information from GitHub in a separate tab.
 
-![GitHub-tab](GitHub-tab.png)
+![GitHub tab in an OpenProject work package](openproject-system-guide-github-integation-github-tab-in-wp.png)
 
-The tab shows all PRs linked to a work package with their corresponding status (e.g. 'Open' or 'Merged') as well as the state (e.g. 'success' or 'queued') of the GitHub actions configured to run for a PR. PRs and work packages are in an n:m relationship, so a work package can be linked to multiple PRs and a PR can be linked to multiple work packages.
+The GitHub tab shows all PRs linked to a work package with their corresponding statuses (e.g. 'Open' or 'Merged') as well as the state (e.g. 'success' or 'queued') of the GitHub actions configured to run for a PR. PRs and work packages are in an n:m relationship, so a work package can be linked to multiple PRs and a PR can be linked to multiple work packages.
 
-Additionally, in your OpenProject work package, the GitHub integration supports you to create a branch straight from the work package and consequently the matching pull request.
+Additionally, in your OpenProject work package, the GitHub integration supports you in creating a branch straight from the work package and the corresponding pull request.
 
-![GitHub-create-branch](GitHub-create-branch.png)
-
-Pull request activities will also show up in the Activity tab when the pull request is
+![Git snippets dropdown menu under GitHub tab in OpenProject work package](openproject-system-guide-github-integation-github-git-snippets.png)
 
+Pull request activities will also appear in the Activity tab when the pull request is:
 * first referenced (usually when opened)
+* marked ready for review
 * merged
 * closed
 
-![Github comments on work package](workpackage-github-comments.png)
-
-## Create a pull request
-
-As pull requests are based on branches, a new branch needs to be created first. For that, open the GitHub tab in your OpenProject work package detail view. Click on 'Git snippets' to extend the menu. First, copy the branch name by clicking the corresponding button.
-
-![GitHub-copy-branch-name](GitHub-copy-branch-name.png)
-
-Then, open your git client, e.g. GitHub desktop or a console. There, you create your branch with the name you copied from your OpenProject work package. That way, all the branches will follow a common pattern and as the OpenProject ID is included in the branch name, it will be easy to see the connection between a PR and a work package when taking a look at a list of PRs on GitHub.
-
-![GitHub-desktop-new-branch](GitHub-desktop-new-branch.png)
-
-With the branch opened, you can start the actual development work using whatever tool you deem to be the best (it is VIM BTW), to alter your codebase.
-
-![GitHub-changes](GitHub-changes.png)
-
-Once you are satisfied with the changes you create a commit. Within the 'Git snippets' menu, OpenProject suggests a commit message for you based on the title and the URL of the work package.
-
-![GitHub_OpenProject-commit-message](GitHub_OpenProject-commit-message.png)
-
-A URL pointing to a work package within a pull request description or a comment will lead to the two entities becoming linked. Using the value in the 'Commit message' input thus helps you to establish that link. The link needs to be in the PR and not in a commit but GitHub will use the first commit message as the proposed branch description (as long as there is only one commit).
-
-![GitHub-commit](GitHub-commit-2645308.png)
-
-Once the branch is published,
-
-![GitHub-publish-branch](GitHub-publish-branch.png)
-
-you create your pull request. Title and comment with the link to the respective OpenProject work package will be prefilled, at least if there is only one commit to the branch. Because of this one commit limitation and if the policy is to create a branch as early as possible, there is a third option in the 'Git snippets' menu ('Create branch with empty commit') that will open a branch and add an empty commit to it in one command. Using this option, one can first create the branch quickly and have it linked to the work package right from the beginning. Commits can of course be added to the branch (and PR) after that.
-
-The branch description can be amended before a PR is created giving the opportunity to further describe the changes. To help with that, it is also possible to copy parts of the work package description since the description can be displayed in the markdown format. Links to additional work packages can also be included in the PR description.
-
-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.
-
-![GitHub-open-pull-request](GitHub-open-pull-request-2645707.png)
-
-Click on **Create pull request** and your pull request will be opened.
-
-![GitHub-pull-request-opened](GitHub-pull-request-opened-2646257.png)
-
-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 status of all the configured GitHub Actions will also be displayed.
-
-![GitHub-action](GitHub-action.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)
+![Github comments on Activity tab of an OpenProject work package](openproject-system-guide-github-integation-github-activity-tab.png)
 
 ## Configuration
 
-You will have to configure both OpenProject and GitHub for the integration to work.
+To enable the integration, you must configure both OpenProject and GitHub.
 
 ### 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
-to see work packages and comment on them.
+First, create a user in OpenProject to make the comments. Add this user to each project with a role that grants permission to view and comment on work packages. 
 
-The role needs two permissions and should only receive those two: "View work packages" and "Add notes" which you will find in the "Work packages and Gantt charts" section.
+First you will need to create a user in OpenProject that has the permission to make comments. We recommend creating a dedicated role and assigning this role to the user. This role only requires two permissions, *View work packages* and *Add notes*, which you will find in the Work packages and Gantt charts section under [Roles and Permissions](../../users-permissions/roles-permissions/).
 
-![GitHub role with 'add notes' permission](github-role.png)
+![GitHub role with necessary permissions in OpenProject administration](openproject-system-guide-github-integation-github-new-role.png)
 
-![GitHub user added as member to project with respective role](github-project-member.png)
+![GitHub user added as member to project with respective role](openproject-system-guide-github-integation-github-new-user.png)
 
 Once the user is created you need to generate an OpenProject API token for this user (you will need it on the GitHub side). For this you have to:
 
@@ -103,32 +50,102 @@ Once the user is created you need to generate an OpenProject API token for this
 3. Go to [*Access Tokens*](../../../user-guide/account-settings/#access-tokens)
 4. Click on **+ API token**
 
+> [!IMPORTANT]
 > Make sure you copy the generated key and securely save it, as you will not be able to retrieve it later.
 
 You can then configure the necessary webhook in GitHub. 
 
 Finally you will need to activate the GitHub module under [Project settings](../../../user-guide/projects/project-settings/modules/) so that all information pulling through from GitHub will be shown in the work packages.
 
-![GitHub-module](Github-module-2647262.png)
+![GitHub module is activated under Project settings -> Modules in OpenProject project](openproject-system-guide-github-integation-github-module.png)
 
-Seeing the 'GitHub' tab requires **Show GitHub content** permission, so this permission needs to be granted to all roles in a project allowed to see the tab.
+To see the 'GitHub' tab, users need the **Show GitHub content** permission. Ensure this is granted to all roles that require access
 
 ### GitHub
 
 In GitHub you have to set up a webhook in each repository to be integrated with OpenProject.
 
-![Create the webhook in GitHub](create-github-webhook.png)
+![Create the webhook in GitHub](openproject-system-guide-github-integation-github-webhook.png)
 
-You need to configure just two things in the webhook.
+Only two settings need to be configured in the webhook.
 The **Content Type** has to be `application/json`.
 The **Payload URL** must point to your OpenProject server's GitHub webhook endpoint (`/webhooks/github`).
 
-> **Note**: For the events that should be triggered by the webhook, please select "Send me everything".
+> [!NOTE]
+> For the events that should be triggered by the webhook, please select "Send me everything".
 
-Now you need the API key you copied earlier. Append it to the *Payload URL* as a simple GET parameter named `key`. In the end the URL should look something like this:
+You will need the API key you copied earlier in OpenProject. Append it to the *Payload URL* as a simple GET parameter named `key`. In the end the URL should look something like this:
 
 `https://myopenproject.com/webhooks/github?key=42`
 
 _Earlier version may have used the `api_key` parameter. In OpenProject 10.4, it is `key`._
 
 Now the integration is set up on both sides and you can use it.
+
+## Using GitHub integration
+
+### Using a Git Desktop Client
+
+As pull requests are based on branches, a new branch needs to be created first. For that, open the GitHub tab in your OpenProject work package detail view. Click on 'Git snippets' to extend the menu. First, copy the branch name by clicking the corresponding button.
+
+![Copy branch name Git snippet from OpenProject Github tab Git snippets menu](openproject-system-guide-github-integation-github-tab-branch-name-snippet.png)
+
+Then, open your GitHub desktop client. There, you create your branch with the name you copied from your OpenProject work package. That way, all the branches will follow a common pattern and as the OpenProject ID is included in the branch name, it will be easy to see the connection between a PR and a work package when taking a look at a list of PRs on GitHub.
+
+![Enter new branch git snippet to your git desktop client](openproject-system-guide-github-desktop-create-branch.png)
+
+Once you click the *Create branch* button, you can directly publish that branch in the next step.
+
+![Publish branch with GitHub Desktop client](openproject-system-guide-github-desktop-publish-branch.png)
+
+With the branch opened, you can start the actual development work using whatever tool you prefer, to alter your codebase.
+
+![GitHub changes](openproject-system-guide-github-integation-github-changes.png)
+
+Once your changes are complete, create a commit. To do that, copy the suggested *Commit message* from the *Git snippets* dropdown menu. It is based on the title and the URL of the work package.
+
+![Commit message in the Git snippets dropdown menu under Github dropdown menu in OpenProject work package](openproject-system-guide-github-integation-github-tab-in-wp-commit-message.png)
+
+A URL pointing to a work package within a pull request description or a comment will lead to the two entities becoming linked. Using the value in the 'Commit message' input thus helps you to establish that link. The link needs to be in the PR and not in a commit but GitHub will use the first commit message as the proposed branch description (as long as there is only one commit).
+
+![Commit message in Github Desktop client](openproject-system-guide-github-integation-commit-message-in-desktop-client.png)
+
+You can now create your pull request by clicking the *Commit* button. Title and comment with the link to the respective OpenProject work package will be prefilled, at least if there is only one commit to the branch. Because of this one commit limitation and if the policy is to create a branch as early as possible, there is a third option in the 'Git snippets' menu ('Create branch with empty commit') that will open a branch and add an empty commit to it in one command. Using this option, one can first create the branch quickly and have it linked to the work package right from the beginning. Commits can of course be added to the branch (and PR) after that.
+
+The branch description can be amended before a PR is created giving the opportunity to further describe the changes. To help with that, it is also possible to copy parts of the work package description since the description can be displayed in the markdown format. Links to additional work packages can also be included in the PR description.
+
+Instead of inserting a full link to the work package, you can reference it by adding 'OP#87' (where 87 is the work package ID) to the pull request description.
+
+![Create pull request in the GitHub web interface](openproject-system-guide-github-integation-create-pr.png)
+
+Click on **Create pull request** and your pull request will be opened. You can then assign it for a review or further modify your PR by adding a new commit. Once the PR is finalized, you can merge it by clicking the respective button.
+
+![Merge an opened GitHub pull request](openproject-system-guide-github-integation-merge-pr.png)
+
+In OpenProject you will see the changes of the PR status under Activity tab. Under GitHub tab you will also see the status change of all the configured GitHub Actions.
+
+![PR changes displayed under OpenProject work package Activity tab](openproject-system-guide-github-integation-github-pr-merged.png)
+
+### Using the Command Line Interface
+
+If you prefer to work with Git via the Command Line Interface (CLI), you can follow a similar process to create and manage pull requests, by following same steps as you would if using a Git Desktop Client. 
+
+You can copy the branch name from the OpenProject work package as described in the Git snippets section above. Then, create and switch to a new branch in your local repository. Modify the necessary files in your repository. Once you are satisfied with the changes, stage and commit them, using the suggested commit message from OpenProject.
+
+![Git snippet to create a new branch in GitHub entered into command line interface](openproject-system-guide-github-integration-branch-git-snippet-cli.png)
+
+When using a CLI you can also use the **Create branch with empty commit** Git snippet. 
+
+![Git snippet to create a branch with empty commit under GitHub tab in a work package in OpenProject](openproject-system-guide-github-integration-git_snippet_empty_commit.png)
+
+The advantage of using this snippet is that there is no need to first create a branch and then copy a separate Git snippet for the commit. A new branch will be created from your current branch along with an empty commit, which when pushed to GitHub will link back to the work package. 
+
+![Git snippet to create a new branch with empty commit in GitHub entered into command line interface](openproject-system-guide-github-integration-branch-and-commit-git-snippet-cli.png)
+
+Continue your work as you normally would, push the branch to GitHub and create a pull request.
+
+![New GitHub pull request created by git snippet entered into CLI](openproject-system-guide-github-new_pull_request_in_github.png)
+
+Changes to the pull request will be tracked under GitHub tab of OpenProject work package, from which git snippets were copied. 
+
+![Pull request changes displayed in an OpenProject work package](openproject-system-guide-github-cli-snippet-work-package.png)

docs/system-admin-guide/integrations/gitlab-integration/README.md

@@ -51,6 +51,7 @@ Once the user is created you need to generate an OpenProject API token for this
 3. Go to [*Access Tokens*](../../../user-guide/account-settings/#access-tokens)
 4. Click on **+ API token**
 
+> [!IMPORTANT]
 > Make sure you copy the generated key and securely save it, as you will not be able to retrieve it later.
 
 You can then configure the necessary webhook in [GitLab](#gitlab).
@@ -75,20 +76,20 @@ You will need the API key you copied earlier in OpenProject. Append it to the *U
 
 `https://myopenproject.com/webhooks/gitlab?key=4221687468163843`
 
-> **Note**: For the events that should be triggered by the webhook, please select the following
->
-> - Push events (all branches)
-> - Comments
-> - Issues events
-> - Merge request events
-> - Pipeline events 
+For the events that should be triggered by the webhook, please select the following
+
+- Push events (all branches)
+- Comments
+- Issues events
+- Merge request events
+- Pipeline events 
 
 
-> **Note**: Please note that the *Pipeline events* part of the integration is still in the early stages. If you have any feedback on the *Pipeline events*, please let us know [here](https://community.openproject.org/wp/54574).
+> [!NOTE] Please note that the *Pipeline events* part of the integration is still in the early stages. If you have any feedback on the *Pipeline events*, please let us know [here](https://community.openproject.org/wp/54574).
 
 
-> **Note**: If you are in a local network you might need to allow requests to the local network in your GitLab instance.  
-> You can find this settings in the **Outbound requests** section when you navigate to **Admin area -> Settings -> Network**.
+> [!TIP] 
+> If you are in a local network you might need to allow requests to the local network in your GitLab instance. You can find this settings in the **Outbound requests** section when you navigate to **Admin area -> Settings -> Network**.
 
 We recommend that you enable the **SSL verification** before you **Add webhook**.
 
@@ -105,13 +106,15 @@ Before upgrading, please do the following:
 
 ## Using GitLab integration
 
-### Create merge requests
+### Using a Git Desktop Client
+
+#### Create merge requests
 
 As merge requests are based on branches, a new branch needs to be created first. For that, open the GitLab tab in your OpenProject work package detailed view. Click on **Git snippets** to extend the menu. First, copy the branch name by clicking the corresponding button.
 
 ![Copy the branch name for GitLab in OpenProject](openproject-system-guide-gitlab-integration-branch-name.png)
 
-Then, open your git client, e.g. Git desktop client or a console. There, you can create your branch by entering the branch name you copied from your OpenProject work package. That way, all the branches will follow a common pattern and as the OpenProject ID is included in the branch name, it will be easy to see the connection between a MR and a work package when taking a look at a list of MRs on GitLab.
+Then, open your Git desktop client. There, you can create your branch by entering the branch name you copied from your OpenProject work package. That way, all the branches will follow a common pattern and as the OpenProject ID is included in the branch name, it will be easy to see the connection between a MR and a work package when taking a look at a list of MRs on GitLab.
 
 ![Create a new branch in a Git desktop client](openproject-system-guide-gitlab-integration-create-branch.png)
 
@@ -157,6 +160,29 @@ If the status of a merge request changes, it will be reflected in the OpenProjec
 
 ![GitLab merge request status change](openproject-system-guide-gitlab-integration-mr-status.png)
 
+### Using the Command Line Interface
+
+If you prefer to work with Git via the Command Line Interface (CLI), you can follow a similar process to create and manage merge requests, by following same steps as you would if using a Git Desktop Client. 
+
+You can copy the branch name from the OpenProject work package as described in the Git snippets section above. Then, create and switch to a new branch in your local repository. Modify the necessary files in your repository. Once you are satisfied with the changes, stage and commit them, using the suggested commit message from OpenProject.
+
+![Git snippet to create a new branch in GitLab entered into command line interface](openproject-system-guide-gitlab-integration-branch-git-snippet-cli.png)
+
+When using a CLI you can also use the **Create branch with empty commit** Git snippet. 
+![Git snippet to create a branch with empty commit under GitLab tab in a work package in OpenProject](openproject-system-guide-gitlab-integration-git_snippet_empty_commit.png)
+
+The advantage of using this snippet is that there is no need to first create a branch and then copy a separate Git snippet for the commit. A new branch will be created from your current branch along with an empty commit, which when pushed to GitLab will link back to the work package.
+
+![Git snippet to create a new branch with empty commit in GitLab entered into command line interface](openproject-system-guide-gitlab-integration-branch-and-commit-git-snippet-cli.png)
+
+Continue your work as you normally would, push the branch to GitLab and create a merge request.
+
+![New GitLab merge request created by git snippet entered into CLI](openproject-system-guide-gitlab-new_merge_request_in_gitlab.png)
+
+Changes to the merge request will be tracked under GitLab tab of OpenProject work package, from which git snippets were copied. 
+
+![Work package in OpenProject showing GitLab tab and related merge request updates](openproject-system-guide-gitlab-cli-snippet-work-package.png)
+
 ### Link issues
 
 OpenProject GitLab integration allows linking GitLab issues directly with OpenProject work packages.
@@ -171,4 +197,4 @@ You can either create a new issue in GitLab, or edit an already existing one. En
 
 Once you save your changes or create a GitLab issue, it will become visible under the **GitLab** tab in OpenProject.
 
-![New GitLab issues shown in OpenProject work packages](openproject-system-guide-gitlab-integration-new-issues.png)
+![New GitLab issues shown in OpenProject work packages](openproject-system-guide-gitlab-integration-new-issues.png)