docs: add a new cookbook section to provide concrete examples of upli…

…ft usage (#339)

.github/workflows/docs.yml

@@ -63,7 +63,7 @@ jobs:
           include: mkdocs.yml
 
       - name: Patch mkdocs.yml Edit URI
-        if: startsWith(github.ref, 'refs/tags/v') || ${{ github.event_name == 'workflow_dispatch' }}
+        if: startsWith(github.ref, 'refs/tags/') || ${{ github.event_name == 'workflow_dispatch' }}
         uses: jacobtomlinson/gha-find-replace@v3
         with:
           find: 'edit_uri: ""'

.gitignore

@@ -17,7 +17,7 @@
 # Built dependencies
 completions/
 manpages/
-uplift
+./uplift
 
 # GoReleaser build output
 dist/
@@ -27,4 +27,4 @@ site/
 .DS_store
 
 # VSCode
-.vscode/
+.vscode/

docs/cookbook/push-options.md

@@ -0,0 +1,25 @@
+# Configure GitLab pipelines with Push Options
+
+Since Git version `2.10`, a client could send arbitrary strings to a server (_remote_) using [push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) (`--push-option`). GitLab has utilized [push options](https://docs.gitlab.com/ee/user/project/push_options.html) to configure pipeline behavior since version `11.7`. This type of configuration opens up many possibilities for configuring your CI/CD workflow through uplift.
+
+## Skip Rebuilding Main Branch
+
+During a release, uplift may commit and push some staged files (_bumped files and changelog_) before tagging the project with the next semantic version. GitLab's default behavior is to spawn two pipelines, one for the main branch and another for the tag. The former may be deemed surplus to requirements and can be skipped using the `ci.skip` push option:
+
+```{ .yaml .annotate linenums="1" }
+git:
+  pushOptions:
+    - option: ci.skip
+      skipTag: true
+```
+
+## Dynamically update CI/CD Variables
+
+Using environment variables to configure pipelines is a common practice within GitLab. It may be desirable in certain conditions to dynamically change their values, and GitLab provides a `ci.variable` push option for this exact purpose.
+
+```{ .yaml .annotate linenums="1" }
+git:
+  pushOptions:
+    - option: ci.variable="CODE_QUALITY_DISABLED=true"
+      skipBranch: true
+```

mkdocs.yml

@@ -83,6 +83,8 @@ nav:
       - Git Repository has a Detached HEAD: faq/gitdetached.md
       - Git Repository contains a Shallow Clone: faq/gitshallow.md
       - GPG Key fails to Import: faq/gpgimport.md
+  - Cookbook:
+      - GitLab Push Options: cookbook/push-options.md
   - Reference:
       - Configuration: reference/config.md
       - CLI: