Update github actions documentation #606

goruha · 2024-05-23T23:08:13Z

what

Update github actions documentation

why

Document the latest gitops

references

DEV-491: Update Atmos.tools documentation for GitHub Actions to use atmos.yaml

website/docs/integrations/github-actions/affected-stacks.md

milldr · 2024-05-23T23:54:47Z

website/docs/integrations/github-actions/atmos-terraform-apply.md

+The action expects the atmos configuration file `atmos.yaml` to be present in the repository.
+The config should have the following structure:

 ```yaml
-  # .github/workflows/atmos-terraform-apply.yaml
-  name: "atmos-terraform-apply"
-
-  on:
-    workflow_dispatch:
-    pull_request:
-      types:
-        - closed
-      branches:
-        - main
-
-  # These permissions are required for GitHub to assume roles in AWS
-  permissions:
-    id-token: write
-    contents: read
-
-  jobs:
-    apply:
-      runs-on: ubuntu-latest
-      steps:
-        - name: Terraform Apply
-          uses: cloudposse/github-action-atmos-terraform-apply@v2
-          with:
-            component: "foobar"
-            stack: "plat-ue2-sandbox"
+# ./rootfs/usr/local/etc/atmos/atmos.yaml
+integrations:
+  github:
+    gitops:
+      terraform-version: 1.5.2
+      infracost-enabled: false
+      artifact-storage:
+        region: us-east-2
+        bucket: cptest-core-ue2-auto-gitops
+        table: cptest-core-ue2-auto-gitops-plan-storage
+        role: arn:aws:iam::xxxxxxxxxxxx:role/cptest-core-ue2-auto-gitops-gha
+      role:
+        plan: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
+        apply: arn:aws:iam::yyyyyyyyyyyy:role/cptest-core-gbl-identity-gitops
+      matrix:
+        sort-by: .stack_slug
+        group-by: .stack_slug | split("-") | [.[0], .[2]] | join("-")
 ```

-with the following configuration as an example:
+> [!IMPORTANT]
+> **Please note!** This GitHub Action only works with `atmos >= 1.63.0`. If you are using `atmos < 1.63.0` please use [`v1` version](https://github.com/cloudposse/github-action-atmos-terraform-plan/tree/v1).


this is all copy and pasted from affected-stacks.md above. Rather than having the same steps on both of these pages, can we create a new page for requirements and then link both these 2 pages to that new page?

That page could also be used for this ticket: https://linear.app/cloudposse/issue/DEV-1693/document-atmos-plan-storage-action-on-atmostools

Good suggestion @milldr! We should put it here https://github.com/cloudposse/atmos/blob/12b5f67974859302fc3edcf0be738a98050f8c10/website/docs/integrations/github-actions/github-actions.mdx

And refer to it in the other documents.

@goruha please see this conversation

website/docs/integrations/github-actions/atmos-terraform-drift-detection.md

milldr

please see comments and consider consolidating setup / config requirements into a single page rather than copy and pasting across each

website/docs/integrations/github-actions/atmos-terraform-apply.md

osterman · 2024-05-25T14:25:06Z

website/docs/integrations/github-actions/atmos-terraform-apply.md

+          stack: "plat-ue2-sandbox"
+          sha: ${{ github.sha }}          
+          atmos-config-path: ./rootfs/usr/local/etc/atmos/
+          atmos-version: 1.63.0


Also, I believe we should consider moving this into the atmos.yaml for a few reasons:

Ensure GitHub Actions and local execution use the same version

Make it optional

It's error prone and easily missed. See this thread in SweetOps

If we support a version parameter, I think it doesn't belong in the integrations section, but more of a top-level section. Let's discuss with @aknysh

we can create a separate section for it. Let's discuss

@osterman

We can not move into atmos.yaml

atmos-config-path: ./rootfs/usr/local/etc/atmos/ atmos-version: 1.63.0

Because this setting is required by GitHub action to install Atmos and get gitops settings from atmos.yml config

* master: Update `atmos validate stacks` command (#611) Add Atmos manifest lists merge strategies (#609) Improve `atmos validate stacks` and `atmos describe affected` commands (#608) Use Darker Theme, Add File Component (#607) Update Atmos logs. Update docs (#605)

milldr · 2024-06-03T19:42:24Z

website/docs/integrations/github-actions/affected-stacks.mdx

+  # This job is an example how to use the affected stacks with the matrix strategy
+  atmos-plan:
+    needs: ["atmos-affected"]
+    if: ${{ needs.atmos-affected.outputs.has-affected-stacks == 'true' }}
+    name: ${{ matrix.stack_slug }}
+    runs-on: ['self-hosted']
+    strategy:
+      max-parallel: 10
+      fail-fast: false # Don't fail fast to avoid locking TF State
+      matrix: ${{ fromJson(needs.atmos-affected.outputs.matrix) }}
+    ## Avoid running the same stack in parallel mode (from different workflows)
+    concurrency:
+      group: ${{ matrix.stack_slug }}
+      cancel-in-progress: false
+    steps:
+      - name: Plan Atmos Component
+        uses: cloudposse/github-action-atmos-terraform-plan@v2
+        with:
+          component: ${{ matrix.component }}
+          stack: ${{ matrix.stack }}
+          atmos-config-path: ./rootfs/usr/local/etc/atmos/
+          atmos-version: 1.63.0


we can remove all of this, since this page is for "affected-stacks"

Suggested change

# This job is an example how to use the affected stacks with the matrix strategy

atmos-plan:

needs: ["atmos-affected"]

if: ${{ needs.atmos-affected.outputs.has-affected-stacks == 'true' }}

name: ${{ matrix.stack_slug }}

runs-on: ['self-hosted']

strategy:

max-parallel: 10

fail-fast: false # Don't fail fast to avoid locking TF State

matrix: ${{ fromJson(needs.atmos-affected.outputs.matrix) }}

## Avoid running the same stack in parallel mode (from different workflows)

concurrency:

group: ${{ matrix.stack_slug }}

cancel-in-progress: false

steps:

- name: Plan Atmos Component

uses: cloudposse/github-action-atmos-terraform-plan@v2

with:

component: ${{ matrix.component }}

stack: ${{ matrix.stack }}

atmos-config-path: ./rootfs/usr/local/etc/atmos/

atmos-version: 1.63.0

website/docs/integrations/github-actions/affected-stacks.mdx

github-actions · 2024-06-08T20:13:50Z

These changes were released in v1.79.0.

Update github actions documentation

12b5f67

goruha requested review from a team as code owners May 23, 2024 23:08

goruha requested review from johncblandii and jamengual May 23, 2024 23:08

goruha temporarily deployed to preview May 23, 2024 23:08 — with GitHub Actions Inactive

milldr reviewed May 23, 2024

View reviewed changes

website/docs/integrations/github-actions/affected-stacks.md Outdated Show resolved Hide resolved

milldr reviewed May 23, 2024

View reviewed changes

website/docs/integrations/github-actions/affected-stacks.md Outdated Show resolved Hide resolved

milldr reviewed May 23, 2024

View reviewed changes

website/docs/integrations/github-actions/atmos-terraform-drift-detection.md Outdated Show resolved Hide resolved

milldr reviewed May 23, 2024

View reviewed changes

website/docs/integrations/github-actions/atmos-terraform-drift-detection.md Outdated Show resolved Hide resolved

milldr requested changes May 23, 2024

View reviewed changes

osterman reviewed May 25, 2024

View reviewed changes

website/docs/integrations/github-actions/atmos-terraform-apply.md Outdated Show resolved Hide resolved

osterman reviewed May 25, 2024

View reviewed changes

Update tips

0fc538c

goruha temporarily deployed to preview May 29, 2024 12:04 — with GitHub Actions Inactive

Addressed comments

51152aa

goruha temporarily deployed to preview May 29, 2024 12:21 — with GitHub Actions Inactive

goruha added 3 commits June 3, 2024 21:29

Address comments

a93e3ec

Added file widget

8ca4ae5

goruha temporarily deployed to preview June 3, 2024 19:37 — with GitHub Actions Inactive

milldr reviewed Jun 3, 2024

View reviewed changes

website/docs/integrations/github-actions/affected-stacks.mdx Outdated Show resolved Hide resolved

Update affected-stacks.mdx

7e09891

goruha temporarily deployed to preview June 4, 2024 09:58 — with GitHub Actions Inactive

milldr previously approved these changes Jun 4, 2024

View reviewed changes

Fix conflict

418506a

goruha dismissed milldr’s stale review via 418506a June 6, 2024 16:04

goruha temporarily deployed to preview June 6, 2024 16:04 — with GitHub Actions Inactive

milldr approved these changes Jun 6, 2024

View reviewed changes

goruha merged commit 4ea538d into main Jun 6, 2024
14 checks passed

goruha deleted the update-github-integration-docs branch June 6, 2024 16:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update github actions documentation #606

Update github actions documentation #606

goruha commented May 23, 2024

milldr May 23, 2024

osterman May 25, 2024

milldr May 29, 2024

milldr left a comment

osterman May 25, 2024

osterman May 25, 2024

aknysh May 25, 2024

goruha May 29, 2024

milldr Jun 3, 2024

github-actions bot commented Jun 8, 2024

Update github actions documentation #606

Update github actions documentation #606

Conversation

goruha commented May 23, 2024

what

why

references

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

milldr left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jun 8, 2024