diff --git a/docs/2.0/docs/pipelines/installation/viamachineusers.mdx b/docs/2.0/docs/pipelines/installation/viamachineusers.mdx index 45d6ead0a9..4e897f8cd4 100644 --- a/docs/2.0/docs/pipelines/installation/viamachineusers.mdx +++ b/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 + @@ -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) -
Why does this token need these permissions? @@ -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,8 +220,6 @@ 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) -
Why does this token need these permissions? @@ -224,6 +227,10 @@ The following is a breakdown of the permissions needed for the `ORG_REPO_ADMIN_T 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:** - + **Create a token for ci-read-only-user** Generate the following token for the `ci-read-only-user`: **Checklist:** + #### PIPELINES_READ_TOKEN diff --git a/docs/2.0/docs/pipelines/previous-versions/upgrading-github-v3-to-v4.md b/docs/2.0/docs/pipelines/previous-versions/upgrading-github-v3-to-v4.md index de7b446938..4ca4f3c004 100644 --- a/docs/2.0/docs/pipelines/previous-versions/upgrading-github-v3-to-v4.md +++ b/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 + +::: diff --git a/docs/2.0/docs/pipelines/previous-versions/upgrading-gitlab-v1-to-v2.md b/docs/2.0/docs/pipelines/previous-versions/upgrading-gitlab-v1-to-v2.md new file mode 100644 index 0000000000..92ee3b6918 --- /dev/null +++ b/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` + + + + +```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 + +``` + + + + +```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 + +``` + + + diff --git a/sidebars/docs.js b/sidebars/docs.js index ffa22970e6..f74e270c04 100644 --- a/sidebars/docs.js +++ b/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", diff --git a/static/img/pipelines/security/INFRA_ROOT_WRITE_TOKEN.png b/static/img/pipelines/security/INFRA_ROOT_WRITE_TOKEN.png deleted file mode 100644 index 894b4a94a6..0000000000 Binary files a/static/img/pipelines/security/INFRA_ROOT_WRITE_TOKEN.png and /dev/null differ diff --git a/static/img/pipelines/security/ORG_REPO_ADMIN_TOKEN.png b/static/img/pipelines/security/ORG_REPO_ADMIN_TOKEN.png deleted file mode 100644 index 0429b13a5e..0000000000 Binary files a/static/img/pipelines/security/ORG_REPO_ADMIN_TOKEN.png and /dev/null differ