Docs | Update references to v0.0.20 + add watch-pattern section

dag-andersen · Oct 22, 2024 · 7ec9ab4 · 7ec9ab4
1 parent fc60787
commit 7ec9ab4
Show file tree

Hide file tree

Showing 7 changed files with 123 additions and 29 deletions.
diff --git a/README.md b/README.md
@@ -54,7 +54,7 @@ The safest way to make changes to you Helm Charts and Kustomize Overlays in your
 >    -v $(pwd)/target-branch:/target-branch \
 >    -e TARGET_BRANCH=helm-example-3 \
 >    -e REPO=dag-andersen/argocd-diff-preview \
->    dagandersen/argocd-diff-preview:v0.0.19
+>    dagandersen/argocd-diff-preview:v0.0.20
 > ```
 > 
 > and the output would be something like this:
@@ -115,7 +115,7 @@ jobs:
             -v $(pwd)/output:/output \
             -e TARGET_BRANCH=${{ github.head_ref }} \
             -e REPO=${{ github.repository }} \
-            dagandersen/argocd-diff-preview:v0.0.19
+            dagandersen/argocd-diff-preview:v0.0.20
 
       - name: Post diff as comment
         run: |

diff --git a/docs/application-selection.md b/docs/application-selection.md
@@ -2,53 +2,134 @@
 
 Rendering the manifests generated by all applications in the repository on each pull request can be slow. Limiting the number of applications rendered can speed up the rendering process significantly. By default, `argocd-diff-preview` will render all applications in the repository.
 
-Here are three ways to limit which applications are rendered:
+Here are _4_ ways to limit which applications are rendered:
 
-## Label Selectors
+## Rendering only changed applications
 
-Run the tool with the `--selector` option to filter applications based on labels. The option supports `=`, `==`, and `!=`.
+You can configure the tool to render only the applications affected by changes in a pull request. This optimizes the rendering process by focusing on the applications directly impacted by the modified files.
+
+To achieve this, you need to add the annotation: `argocd-diff-preview/watch-pattern` to all your Applications/ApplicationSets, and provide the tool with a list of changed files. If no list is provided, the annotation will be ignored.
 
 *Example:*
-```bash
-argocd-diff-preview --selector "team=a"
-```
-This command :arrow_up: will target the following application :arrow_down: and ignore all applications that do not have the label `team: a`.
 
-```yaml
+By adding the annotation `argocd-diff-preview/watch-pattern: "examples/.*"` to the Application manifest, the `my-app` application will only be rendered if a file in the `examples/` folder is modified in the PR. However, the `my-app` application will also be rendered if its own `Application` manifest is changed, so there's no need to include the application's file path in the watch-pattern annotation.
+
+```yaml title="Application" hl_lines="7"
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
   name: my-app
-  labels:
-    team: a
+  namespace: argocd
+  annotations:
+    argocd-diff-preview/watch-pattern: "examples/.*" # Regex
 spec:
   ...
 ```
 
-## Annotations
+#### How to use it in a GitHub Actions Workflow
 
-You can exclude specific applications from rendering by adding the annotation `argocd-diff-preview/ignore: "true"` to their manifest. This is useful for skipping applications that don’t require a diff.
+You can use the [`tj-actions/changed-files`](https://github.com/tj-actions/changed-files) action in your workflow and pass the output to the `argocd-diff-preview` tool. Providing the tool with a list of changed files will ensure you only render applications that watch those file paths. Any application without the `argocd-diff-preview/watch-pattern` annotation will be ignored.
 
-*Example:*
-```yaml
+```yaml title=".github/workflows/generate-diff.yml" linenums="1" hl_lines="16-18 39"
+name: Generate Diff Tool Change
+
+on:
+  pull_request:
+    branches:
+      - "main"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+
+    steps:
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v45
+
+      - uses: actions/checkout@v4
+        with:
+          path: pull-request
+
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          path: main
+
+      - name: Generate Diff
+        run: |
+          docker run \
+            --network=host \
+            -v /var/run/docker.sock:/var/run/docker.sock \
+            -v $(pwd)/main:/base-branch \
+            -v $(pwd)/pull-request:/target-branch \
+            -v $(pwd)/output:/output \
+            -e TARGET_BRANCH=${{ github.head_ref }} \
+            -e REPO=${{ github.repository }} \
+            -e FILES_CHANGED="${{ steps.changed-files.outputs.all_changed_files }}"
+            dagandersen/argocd-diff-preview:v0.0.20
+```
+
+## Ignoring individual applications
+
+You can exclude specific applications from rendering by adding the annotation `argocd-diff-preview/ignore: "true"` to their manifest. This is useful for skipping applications that don’t require a diff preview.
+
+*Examples:*
+```yaml title="Application" hl_lines="7"
 apiVersion: argoproj.io/v1alpha1
 kind: Application
 metadata:
   name: my-app
+  namespace: argocd
   annotations:
     argocd-diff-preview/ignore: "true"
 spec:
   ...
 ```
 
-## File Regex
+```yaml title="ApplicationSet" hl_lines="6"
+apiVersion: argoproj.io/v1alpha1
+kind: ApplicationSet
+metadata:
+  name: my-app
+  annotations:
+    argocd-diff-preview/ignore: "true"
+spec:
+  ...
+```
+
+## Label Selectors
+
+Run the tool with the `--selector` option to filter applications based on labels. The option supports `=`, `==`, and `!=`.
+
+*Example:*
+```bash
+argocd-diff-preview --selector "team=a"
+```
+This command :arrow_up: will target the following application :arrow_down: and ignore all applications that do not have the label `team: a`.
+
+```yaml title="Application" hl_lines="5-6"
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: my-app
+  labels:
+    team: a
+spec:
+  ...
+```
+
+## Application File Path Regex
 
-Alternatively, use the `--file-regex` option to limit rendering to manifests whose file paths match a regular expression. This is helpful when rendering changes from specific teams or directories.
+Alternatively, use the `--file-regex` option to limit rendering to Applications whose file paths match a regular expression. This is helpful when rendering changes from specific teams or directories.
 
 *Example:*
 
-If someone in your organization from *Team A* changes to one of their applications, the tool can be run with:
+If someone in your organization from *Team A* changes one of their applications, the tool can be run with:
 ```bash
 argocd-diff-preview --file-regex="/Team-A/"
 ```
-This ensures only applications in folders matching `*/Team-A/*` are rendered.
+This ensures only applications in folders matching `*/Team-A/*` are rendered.
diff --git a/docs/demo.md b/docs/demo.md
@@ -17,7 +17,7 @@ docker run \
    -v $(pwd)/target-branch:/target-branch \
    -e TARGET_BRANCH=helm-example-3 \
    -e REPO=dag-andersen/argocd-diff-preview \
-   dagandersen/argocd-diff-preview:v0.0.19
+   dagandersen/argocd-diff-preview:v0.0.20
 ```
 
 and the output would be something like this:

diff --git a/docs/github-actions-workflow.md b/docs/github-actions-workflow.md
@@ -39,7 +39,7 @@ jobs:
             -v $(pwd)/output:/output \
             -e TARGET_BRANCH=${{ github.head_ref }} \
             -e REPO=${{ github.repository }} \
-            dagandersen/argocd-diff-preview:v0.0.19
+            dagandersen/argocd-diff-preview:v0.0.20
 
       - name: Post diff as comment
         run: |
@@ -53,7 +53,7 @@ jobs:
 
 In the simple code examples above, we do not provide the cluster with any credentials, which only works if the image/Helm Chart registry and the Git repository are public. Since your repository might not be public you need to provide the tool with the necessary read-access credentials for the repository. This can be done by placing the Argo CD repo secrets in folder mounted at `/secrets`. When the tool starts, it will simply run `kubectl apply -f /secrets` to apply every resource to the cluster, before starting the rendering process.
 
-```yaml title=".github/workflows/generate-diff.yml" linenums="19"
+```yaml title=".github/workflows/generate-diff.yml" linenums="19" hl_lines="7-22 32"
 ...
     - uses: actions/checkout@v4
       with:
@@ -88,7 +88,7 @@ In the simple code examples above, we do not provide the cluster with any creden
           -v $(pwd)/secrets:/secrets \           ⬅️ Mount the secrets folder
           -e TARGET_BRANCH=${{ github.head_ref }} \
           -e REPO=${{ github.repository }} \
-          dagandersen/argocd-diff-preview:v0.0.19
+          dagandersen/argocd-diff-preview:v0.0.20
 ```
 
 For more info, see the [Argo CD docs](https://argo-cd.readthedocs.io/en/stable/operator-manual/argocd-repo-creds-yaml/)
diff --git a/docs/installation.md b/docs/installation.md
@@ -2,7 +2,7 @@
 
 === "Docker"
 
-    ## Pre-requisites:
+    ## Pre-requisites
 
     - Install: [Docker](https://docs.docker.com/get-docker/)
 
@@ -28,14 +28,14 @@
       -e TARGET_BRANCH=<branch-a> \
       -e BASE_BRANCH=<branch-b> \
       -e REPO=<owner>/<repo>  \
-      dagandersen/argocd-diff-preview:v0.0.19
+      dagandersen/argocd-diff-preview:v0.0.20
     ```
 
     If base-branch(`BASE_BRANCH`) is not specified it will default to `main`.
 
 === "Binary"
 
-    ## Pre-requisites:
+    ## Pre-requisites
 
     Install:
 
@@ -52,7 +52,7 @@
     *Example for downloading and running on macOS:*
 
     ```bash
-    curl -LJO https://github.com/dag-andersen/argocd-diff-preview/releases/download/v0.0.19/argocd-diff-preview-Darwin-x86_64.tar.gz
+    curl -LJO https://github.com/dag-andersen/argocd-diff-preview/releases/download/v0.0.20/argocd-diff-preview-Darwin-x86_64.tar.gz
     tar -xvf argocd-diff-preview-Darwin-x86_64.tar.gz
     sudo mv argocd-diff-preview /usr/local/bin
     argocd-diff-preview --help
@@ -81,7 +81,7 @@
 
 === "Source"
 
-    ## Pre-requisites:
+    ## Pre-requisites
 
     Install:
 

diff --git a/docs/options.md b/docs/options.md
@@ -30,6 +30,12 @@ OPTIONS:
                 Regex to filter files. Example: "/apps_.*\.yaml" 
                 [env: FILE_REGEX=]
 
+        --files-changed <files-changed>
+                List of files changed between the two branches.
+                Input must be a comma or space separated list of strings.
+                When provided, only Applications watching these files will be rendered
+                [env: FILES_CHANGED=]
+
     -c, --line-count <line-count>
                 Generate diffs with <n> lines above and below the highlighted 
                 changes in the diff. 

diff --git a/makefile b/makefile
@@ -40,3 +40,10 @@ run-with-docker: pull-repostory
 		-e SELECTOR="$(selector)" \
 		-e FILES_CHANGED="$(files_changed)" \
 		image
+
+mkdocs:
+	pip install mkdocs-material \
+	&& python3 -m venv venv \
+	&& source venv/bin/activate \
+	&& open http://localhost:8000 \
+	&& mkdocs serve