Add Gitlab pipelines v1 to v2 upgrade docs

docs/2.0/docs/pipelines/installation/viamachineusers.mdx

@@ -6,7 +6,7 @@ toc_max_heading_level: 4
 
 # Creating Machine Users
 
-import PersistentCheckbox from '/src/components/PersistentCheckbox';
+import PersistentCheckbox from "/src/components/PersistentCheckbox"
 import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
 
@@ -39,6 +39,7 @@ If screen sharing while generating tokens, **pause or hide your screen** before
 :::
 
 ### Token types
+
 <Tabs groupId="platform">
 <TabItem value="github" label="GitHub" default>
 
@@ -163,14 +164,13 @@ This [fine-grained](#fine-grained-tokens) Personal Access Token allows GitHub Ac
 
 This token must have the following permissions to the `INFRA_ROOT_WRITE_TOKEN` for the `infrastructure-live-root` repository:
 
+- **Actions:** Read & write access — Allows Pipelines to create enriched pull request comments.
 - **Content:** Read & write access — Required to clone the repository and push changes.
 - **Issues:** Read & write access — Allows Pipelines to open issues when manual intervention is needed.
 - **Metadata:** Read access — Grants access to repository metadata.
 - **Pull requests:** Read & write access — Enables Pipelines to automate infrastructure changes through PRs.
 - **Workflows:** Read & write access — Needed to update workflow files in `.github/workflows` when provisioning new repositories.
 
-![INFRA_ROOT_WRITE_TOKEN PAT Configuration](/img/pipelines/security/INFRA_ROOT_WRITE_TOKEN.png)
-
 <details>
 
 <summary>Why does this token need these permissions?</summary>
@@ -179,6 +179,10 @@ Below is a detailed breakdown of the permissions needed for the `INFRA_ROOT_WRIT
 
 If you are not an Enterprise customer or prefer Pipelines not to execute certain behaviors, you can opt not to grant the related permissions.
 
+##### Actions read & write access
+
+Allows Pipelines to create workflow job artifacts and access workflow job logs to enrich pull request comments with the latest workflow run logs.
+
 ##### Content read & write access
 
 Needed for cloning `infrastructure-live-root` and pushing automated changes. Without this permission, the pull request opened by the GitHub Actions workflow will not trigger automation during account vending.
@@ -205,6 +209,7 @@ Required to update workflows when provisioning new repositories.
 
 This fine-grained token is used for initial setup and bootstrapping repositories. For Enterprise customers, it also provisions delegated repositories. Assign the following permissions to all accessible repositories:
 
+- **Actions:** Read & write access — Allows Pipelines to create enriched pull request comments.
 - **Administration:** Read & write access — Required to create and manage repositories.
 - **Content:** Read & write access — Necessary for reading and writing repository files.
 - **Metadata:** Read access — Grants access to repository metadata.
@@ -215,15 +220,17 @@ This fine-grained token is used for initial setup and bootstrapping repositories
 
 - **Members:** Read & write access — Needed to manage team access for repositories.
 
-![ORG_REPO_ADMIN_TOKEN PAT Configuration](/img/pipelines/security/ORG_REPO_ADMIN_TOKEN.png)
-
 <details>
 <summary>Why does this token need these permissions?</summary>
 
 The following is a breakdown of the permissions needed for the `ORG_REPO_ADMIN_TOKEN`, based on our testing. Permissions were gradually added to identify the minimal set necessary to support Pipelines. Some permissions apply to specific actions, while others are exclusive to Enterprise customers.
 
 If you are not an Enterprise customer or prefer Pipelines not to carry out certain actions, you can choose to withhold the related permissions.
 
+##### Actions read & write access
+
+Allows Pipelines to create workflow job artifacts and access workflow job logs to enrich pull request comments with the latest workflow run logs.
+
 ##### Administration read & write access
 
 Allows the creation of new repositories for delegated infrastructure management.
@@ -266,13 +273,14 @@ Invite `ci-user-read-only` to your `infrastructure-live-root` repository with re
 
 **Checklist:**
 
-<PersistentCheckbox id="via-machine-users-4" label="ci-read-only-user invited to infrastructure-live-root" />
+<PersistentCheckbox id="via-machine-users-4" label="ci-read-only-user invited to infrastructure-live-root" /> 
 
 **Create a token for ci-read-only-user**
 
 Generate the following token for the `ci-read-only-user`:
 
 **Checklist:**
+
 <PersistentCheckbox id="via-machine-users-5" label="PIPELINES_READ_TOKEN created under ci-read-only-user" />
 
 #### PIPELINES_READ_TOKEN

docs/2.0/docs/pipelines/previous-versions/upgrading-github-v3-to-v4.md

@@ -113,7 +113,7 @@ The `accounts.hcl` file is a helper to read from the root `accounts.yml` file in
 
 ### Environments Configuration
 
-For each account in your repository add an environment-**accountname**.hcl file. e.g. for the management account add the following file:
+For each account in your repository add an environment-**AccountName**.hcl file. e.g. for the management account add the following file:
 
 ```hcl title=".gruntwork/environment-management.hcl"
 # Configurations that are applicable to a specific environment within a repository, see: https://docs.gruntwork.io/2.0/reference/pipelines/configurations-as-code/api/#environment-block
@@ -311,3 +311,20 @@ Update the `uses:` field of the GruntworkPipelines job to reference `@v4`
 - [ ] Pipelines Unlock Uses @v4
 
 :::
+
+## Updating CI User Token Permissions
+
+Update both of the CI User's Fine-Grained Personal Access Tokens (PATs):
+
+- [INFRA_ROOT_WRITE_TOKEN](/2.0/docs/pipelines/installation/viamachineusers#infra_root_write_token) and
+- [ORG_REPO_ADMIN_TOKEN](/2.0/docs/pipelines/installation/viamachineusers#org_repo_admin_token)
+
+to include `Actions: Read & write access`. This allows Pipelines to create enriched pull request comments with the latest workflow run logs.
+
+Customers using the [Gruntwork.io GitHub App](/2.0/docs/pipelines/installation/viagithubapp#gruntworkio-github-app) should also update the above permissions so that the tokens already have the necessary permissions when used as a fallback mechanism.
+
+:::note Progress Checklist
+
+- [ ] Updated CI User Token Permissions
+
+:::

docs/2.0/docs/pipelines/previous-versions/upgrading-gitlab-v1-to-v2.md

@@ -0,0 +1,107 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Upgrading Pipelines GitLab Workflows From v1 to v2
+
+To upgrade Pipelines from v1 to v2, perform the following changes in each
+repository that includes the Gruntwork Pipelines Workflows.
+
+## Updating Terragrunt Version
+
+The minimum supported Terragrunt version in v4 is **0.86.3**.
+
+In `.mise.toml` in the root of the repository, update the `terragrunt` version e.g.
+
+```
+terragrunt = "0.86.3"
+```
+
+See the [Terragrunt Release Notes](https://github.com/gruntwork-io/terragrunt/releases)
+for detailed information on the changes to Terragrunt.
+
+:::note Progress Checklist
+
+- [ ] Terragrunt Version Updated
+
+:::
+
+## Pipelines Workflow
+
+In your infrastructure-live repository, replace the contents of the v1 `.gitlab-ci.yml` file with the v2 `.gitlab-ci.yml`. See the v1 and v2 content below.
+
+### Change Summary
+
+- Spec inputs added to allow running Drift Detection and Unlock Unit workflows
+- Pipelines Workflow job updated to reference `@v2`
+
+<Tabs groupId="gitlab-ci-yml">
+<TabItem value="v2-yaml" label="v2">
+
+```yaml title=".gitlab-ci.yml"
+spec:
+  inputs:
+    pipelines_workflow:
+      default: "infrachanges"
+      options: ["infrachanges", "drift-detection", "unlock-unit", "unlock-all"]
+    pipelines_drift_detection_filter:
+      type: string
+      description: "[drift-detection] Limit drift detection to units matching filter https://docs.gruntwork.io/2.0/docs/pipelines/guides/running-drift-detection#drift-detection-filter"
+      default: ""
+    pipelines_drift_detection_branch:
+      type: string
+      description: "[drift-detection] The branch name used for drift remediation MRs"
+      default: "drift-detection"
+    pipelines_unlock_unit_path:
+      type: string
+      description: "[unlock-unit] Path to the Terragrunt Unit directory where the lock is held (everything up to but not including terragrunt.hcl)"
+      default: ""
+    pipelines_unlock_unit_lock_id:
+      type: string
+      description: "[unlock-unit] The ID of the lock, usually a GUID. This is generally found in the console output when Terraform/OpenTofu command fails due to a timeout waiting to acquire a lock"
+      default: ""
+    pipelines_unlock_unit_stack_path:
+      type: string
+      description: "[unlock-unit] Path to a Terragrunt Stack directory (everything up to but not including terragrunt.stack.hcl) that generates content required to run unlock in a specified Terragrunt Unit"
+      default: ""
+---
+workflow:
+  name: GruntworkPipelines
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+include:
+  - component: gitlab.com/gruntwork-io/pipelines-workflows/pipelines@v2
+    inputs:
+      pipelines_workflow: $[[ inputs.pipelines_workflow ]]
+      pipelines_drift_detection_filter: $[[ inputs.pipelines_drift_detection_filter ]]
+      pipelines_drift_detection_branch: $[[ inputs.pipelines_drift_detection_branch ]]
+      pipelines_unlock_unit_path: $[[ inputs.pipelines_unlock_unit_path ]]
+      pipelines_unlock_unit_lock_id: $[[ inputs.pipelines_unlock_unit_lock_id ]]
+      pipelines_unlock_unit_stack_path: $[[ inputs.pipelines_unlock_unit_stack_path ]]
+
+variables:
+  GIT_DEPTH: 0
+
+```
+
+</TabItem>
+<TabItem value="v1-yaml" label="v1">
+
+```yaml title=".gitlab-ci.yml-v1"
+workflow:
+  name: GruntworkPipelines
+  rules:
+    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+
+include:
+  - component: gitlab.com/gruntwork-io/pipelines-workflows/pipelines@v1
+
+variables:
+  GIT_DEPTH: 0
+
+```
+
+</TabItem>
+</Tabs>

sidebars/docs.js

@@ -414,6 +414,11 @@ const sidebar = [
         type: "doc",
         id: "2.0/docs/pipelines/previous-versions/upgrading-github-v3-to-v4",
       },
+      {
+        label: "Upgrading from Pipelines GitLab Workflows v1 to v2",
+        type: "doc",
+        id: "2.0/docs/pipelines/previous-versions/upgrading-gitlab-v1-to-v2",
+      },
       {
         label: "Upgrading from Infrastructure-Pipelines",
         type: "doc",