Update DevOps article to include some examples/links on performing Git operations using the Git Project Tool #6614

source/by-role/developer/devcontentops.rst

@@ -120,7 +120,7 @@ addresses this problem.
 For the single repository approach, the branches will look like the following
 
 .. list-table::
-    :widths: 10 45 45
+    :widths: 14 43 43
     :header-rows: 1
 
     * - Branch
@@ -175,7 +175,7 @@ Given the environments listed above, for the one upstream repository per environ
         dev
       - \- |br|
         QA/qa
-    * - Develepor A Fork
+    * - Developer A Fork
       - studio-dev |br|
         dev-a-fork
       - \- |br|
@@ -188,7 +188,6 @@ The repositories are set up as forks of one another. Depending on your external
 """"
 Flow
 """"
-
 Referring back to the figure above, code flows following the steps
 
 - The developer forks the *Dev* repository's *dev* branch creating *dev-a-fork*
@@ -209,6 +208,68 @@ Referring back to the figure above, code flows following the steps
 - To deploy and test the code on the shared development environment, code flows from *dev* to *studio-dev*, and is then pulled into Crafter Studio.
 - Code is similarly pushed from *dev* to *qa* and again to production (see diagram above)
 
+""""""""""""""""""""""""""""""""""""
+Using the Git Project Tool in Studio
+""""""""""""""""""""""""""""""""""""
+The steps above describe code and content moving between Git branches and external repositories. On each Crafter Studio authoring environment, the :ref:`Git project tool <project-tools-git>` is how developers and DevOps personnel sync the project's sandbox repository with those shared branches.
+
+Open it from the **Sidebar** by clicking on |projectTools|, then **Git**. From there you can add a remote repository, pull changes into Studio, and push sandbox commits to a remote when appropriate. For UI walk-throughs of each operation, see :ref:`project-tools-git`.
+
+The Git project tool is typically used **after** branch promotion work has been done in your Git server (merge, pull request, or fast-forward on the target branch). Studio pulls the result into the authoring environment so authors and developers can preview and test against the updated sandbox.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example: Deploy Code to Delivery Dev
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+After a feature branch is merged into *dev* (code forward) and the *studio-dev* branch is updated on the Git server:
+
+#. On the ``Authoring Dev`` (the authoring environment), ensure the project is linked to the upstream repository (see :ref:`create-project-based-on-a-blueprint-then-add-a-remote-bare-git-repository` if the remote is not yet configured). The upstream repository should be the *studio-dev* branch on *Dev* on the ``Git Server``.
+#. In the Git project tool, pull from the remote branch that tracks *studio-dev* (or the branch your team uses for the Dev Studio sandbox), by clicking on the down arrow next to the remote repository branch that tracks the *studio-dev* branch on the ``Git server``.
+#. Review the changes in Studio, then publish as needed so Delivery Dev is updated.
+
+This corresponds to the step in the flow :ref:`above <devcontentops-flow-diagram>` where code moves from *dev* to *studio-dev* on the Git server and is then pulled into Crafter Studio in ``Authoring Dev``.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example: Promote Code to QA or Prod
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The same pattern applies when promoting code forward to QA and Prod:
+
+#. Merge or promote code on the ``Git Server`` (for example, from *dev* to *qa*, or from *qa* to *prod*) via a PR.
+#. On the **QA** or **Prod** authoring environment, use the Git project tool to pull the updated *studio-qa* or *studio-prod* branch on the ``Git Server`` into Studio by clicking on the down arrow next to the desired remote repository branch.
+#. Validate in Studio (and Staging, if enabled), then publish to the target delivery environment.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example: Sync a Developer Workstation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When a developer creates an orphan project from *dev-a-fork* or needs to align a local Studio sandbox with their fork:
+
+#. Add the developer's fork as a remote in the Git project tool on the ``Developer Workstation``.
+#. Pull from the *dev-a-fork* branch (or the feature branch being actively developed).
+#. Continue Studio-side work, carrying patches to the local *feature-x* branch in the IDE as described above.
+
+To publish IDE work back to the shared flow, push from the workstation to the fork and open a pull request into *dev*—not directly into *studio-dev* on the ``Git Server``.
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Example: Pull Content Back into Studio
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+After a *Content Back* operation syncs production content from *studio-prod* into *prod* then *prod* to *dev* (or *qa*) on the ``Git Server``, the updated content must still be pulled into the lower authoring environments:
+
+#. Confirm the content merge landed on the target branch in your ``Git Server``.
+#. On the **Dev** or **QA** authoring environment, pull that branch into Studio using the Git project tool, by clicking on the down arrow next to the desired remote repository branch.
+#. If blob storage is in use, sync blob content separately as described in :ref:`Blob Storage and Content Back <devcontentops-blob-storage-content-back>` below.
+
+.. note::
+   *Content Back* merges happen on the *dev*, *qa*, or *prod* branches—not by pulling from *studio-qa* into *qa* or from *studio-dev* into *dev*. The Git project tool pulls **into** Studio; it does not replace the Git server-side promotion steps described earlier.
+
+~~~~~~~~~~~~~~~~~~~
+Important Practices
+~~~~~~~~~~~~~~~~~~~
+- **Pull into Studio; promote in Git.** Use your external Git service for merges, pull requests, and branch protection. Use the Git project tool to bring the result into Studio's sandbox.
+- **Respect path conventions.** Avoid pushing author-owned paths (such as ``/site/*`` and ``/static-assets/content/*``) from lower environments upstream. See the path conventions in the next section.
+- **Resolve conflicts locally when possible.** If a pull into Studio reports a conflict, prefer resolving it on a developer workstation or in your Git service, then pull again. The Git project tool provides basic conflict options for emergencies; see the note in :ref:`project-tools-git`.
+- **Publish after pulling.** A successful pull updates the sandbox repository. Use **Project Tools → Publishing** to deploy pulled changes to preview or delivery targets when required (see :ref:`project-tools-git`).
+
+|
+
 """""""""""""""""""""""""""""""""""""""""""""""""""""""
 What Should and Shouldn’t Be Moved Between Environments
 """""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -304,6 +365,8 @@ If developers or QA personnel have created content items with the same path as p
 
 These conflicts can be resolved exactly the same way as code conflicts. The simplest resolution would be to accept the content coming from *dev* or from *qa*. Still, the repository will be able to handle selecting the item that's present in the *studio-* branches as well. Just keep in mind that production content won't make it to the CrafterCMS environment because of the way the conflict was resolved.
 
+.. _devcontentops-blob-storage-content-back:
+
 """""""""""""""""""""""""""""
 Blob Storage and Content Back
 """""""""""""""""""""""""""""