Update README.md (#1056)

int128 · Feb 18, 2024 · 2657528 · 2657528
1 parent 135b50e
commit 2657528
Showing 1 changed file with 39 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -2,26 +2,24 @@
 
 This is a Kubernetes Controller to notify a change of Argo CD Application status.
 
-
 ## Example: Pull Request notification
 
 In the [GitOps](https://www.weave.works/technologies/gitops/) way, you merge a pull request to deploy a change to Kubernetes cluster.
-argocd-commenter allows you to receive a notification after merge.
+argocd-commenter allows you to receive a notification comment after merging.
 
-When an Application is syncing, synced or healthy, argocd-commenter creates a comment.
-It determines a pull request from revision of Application.
+When an Application is syncing, synced or healthy, argocd-commenter will create a comment.
 
-![image](https://user-images.githubusercontent.com/321266/139166345-8edd77cb-319a-43df-b09a-40c18de74716.png)
+<img width="900" alt="image" src="https://github.com/int128/argocd-commenter/assets/321266/f94d45fe-905f-461c-9c4c-8d7a8f7978bf">
 
-When the sync was failed, argocd-commenter creates a comment.
+When the sync was failed, argocd-commenter will create a comment.
 
-![image](https://user-images.githubusercontent.com/321266/139166379-78b431b0-4439-4c86-9280-566424501ac4.png)
+<img width="900" alt="image" src="https://github.com/int128/argocd-commenter/assets/321266/a442bbe8-cb79-4c7e-95b7-cbe5eae7a44d">
 
-See the examples in [e2e test fixtures](https://github.com/int128/argocd-commenter-e2e-test/pulls?q=is%3Apr+is%3Aclosed).
+See the examples in [e2e-test fixtures](https://github.com/int128/argocd-commenter-e2e-test/pulls?q=is%3Apr+is%3Aclosed).
 
 ### Sequence diagram
 
-You will receive a comment when an Argo CD Application is changed.
+Here is the sequence diagram of the deployment flow.
 
 ```mermaid
 sequenceDiagram
@@ -48,37 +46,32 @@ sequenceDiagram
   end
 ```
 
-
 ## Example: GitHub Deployment notification
 
 In a complex deployment flow, you can receive a notification using GitHub [Deployments](https://docs.github.com/en/rest/reference/deployments) API.
-For example, if you deploy a preview environment for a pull request, you can receive notifications via GitHub Deployment.
+For example, when you deploy a preview environment for a pull request, you can receive the deployment statuses.
 
-You need to create a Deployment to receive notifications.
-If an Application contains the following annotation,
+To receive a deployment status, set the following annotation to the Argo CD Application:
 
 ```yaml
+apiVersion: argoproj.io/v1alpha1
+kind: Application
 metadata:
   annotations:
     argocd-commenter.int128.github.io/deployment-url: https://api.github.com/repos/OWNER/REPO/deployments/ID
 ```
 
-argocd-commenter creates a deployment status for the deployment.
-Finally you will see the following statuses:
-
-![image](https://user-images.githubusercontent.com/321266/139166278-e74f6d1b-c722-430f-850c-2f7135e251d6.png)
-
 Here is an example of workflow to deploy a preview environment:
 
 ```yaml
 jobs:
   deploy:
-        steps:
-      # create a deployment
+    steps:
+      # Create a deployment
       - uses: int128/deployment-action@v1
         id: deployment
 
-      # generate manifests for preview environment
+      # Generate the manifests for a preview environment
       - uses: actions/checkout@v2
         with:
           repository: your/manifests-repository
@@ -89,18 +82,22 @@ jobs:
           cd "manifests-repository/pr-${{ github.event.pull_request.number }}"
           sed -e 's|DEPLOYMENT_URL|${{ steps.deployment.outputs.url }}|g' applications/*.yaml
 
-      # push manifests for preview environment
+      # Push the manifests for a preview environment
       - run: |
           git add .
           git commit -m 'Deploy pr-${{ github.event.pull_request.number }}'
           git push manifests-repository main
 ```
 
+When the Application status is changed, argocd-commenter will create a deployment status.
+
+![image](https://user-images.githubusercontent.com/321266/139166278-e74f6d1b-c722-430f-850c-2f7135e251d6.png)
+
 See the [e2e test](https://github.com/int128/argocd-commenter/blob/main/.github/workflows/docker.yaml) for details.
 
 ### Sequence diagram
 
-You will receive a deployment status when an Argo CD Application is changed.
+Here is the sequence diagram of the deployment flow.
 
 ```mermaid
 sequenceDiagram
@@ -138,7 +135,6 @@ sequenceDiagram
   end
 ```
 
-
 ## Getting Started
 
 ### Prerequisite
@@ -156,40 +152,40 @@ kubectl apply -f https://github.com/int128/argocd-commenter/releases/download/v1
 You need to create either Personal Access Token or GitHub App.
 
 - Personal Access Token
-    - Belong to a user
-    - Share the rate limit in a user
+  - Belong to a user
+  - Share the rate limit in a user
 - GitHub App
-    - Belong to a user or organization
-    - Have each rate limit for an installation
+  - Belong to a user or organization
+  - Have each rate limit for an installation
 
-#### Option 1: Personal Access Token
+#### Option 1: Using a Personal Access Token
 
 1. Open https://github.com/settings/tokens
 1. Generate a new token
 1. Create a secret as follows:
-    ```shell
-    kubectl -n argocd-commenter-system create secret generic controller-manager \
-      --from-literal="GITHUB_TOKEN=$YOUR_PERSONAL_ACCESS_TOKEN"
-    ```
+   ```shell
+   kubectl -n argocd-commenter-system create secret generic controller-manager \
+     --from-literal="GITHUB_TOKEN=$YOUR_PERSONAL_ACCESS_TOKEN"
+   ```
 
-#### Option 2: GitHub App
+#### Option 2: Using a GitHub App
 
 1. Create your GitHub App from either link:
-    - For a user: https://github.com/settings/apps/new?name=argocd-commenter&url=https://github.com/int128/argocd-commenter&webhook_active=false&contents=read&pull_requests=write
-    - For an organization: https://github.com/organizations/:org/settings/apps/new?name=argocd-commenter&url=https://github.com/int128/argocd-commenter&webhook_active=false&contents=read&pull_requests=write (replace `:org` with your organization)
+   - For a user: https://github.com/settings/apps/new?name=argocd-commenter&url=https://github.com/int128/argocd-commenter&webhook_active=false&contents=read&pull_requests=write
+   - For an organization: https://github.com/organizations/:org/settings/apps/new?name=argocd-commenter&url=https://github.com/int128/argocd-commenter&webhook_active=false&contents=read&pull_requests=write (replace `:org` with your organization)
 1. Get the **App ID** from the setting page
 1. [Download a private key of the GitHub App](https://docs.github.com/en/developers/apps/authenticating-with-github-apps)
 1. [Set a custom badge for the GitHub App](https://docs.github.com/en/developers/apps/creating-a-custom-badge-for-your-github-app)
-    - Logo of Argo CD is available in [CNCF Branding](https://cncf-branding.netlify.app/projects/argo/)
+   - Logo of Argo CD is available in [CNCF Branding](https://cncf-branding.netlify.app/projects/argo/)
 1. [Install your GitHub App on your repository or organization](https://docs.github.com/en/developers/apps/installing-github-apps)
 1. Get the **Installation ID** from the URL, like `https://github.com/settings/installations/ID`
 1. Create a secret as follows:
-    ```shell
-    kubectl -n argocd-commenter-system create secret generic controller-manager \
-      --from-literal="GITHUB_APP_ID=$YOUR_GITHUB_APP_ID" \
-      --from-literal="GITHUB_APP_INSTALLATION_ID=$YOUR_GITHUB_APP_INSTALLATION_ID" \
-      --from-file="GITHUB_APP_PRIVATE_KEY=/path/to/private-key.pem"
-    ```
+   ```shell
+   kubectl -n argocd-commenter-system create secret generic controller-manager \
+     --from-literal="GITHUB_APP_ID=$YOUR_GITHUB_APP_ID" \
+     --from-literal="GITHUB_APP_INSTALLATION_ID=$YOUR_GITHUB_APP_INSTALLATION_ID" \
+     --from-file="GITHUB_APP_PRIVATE_KEY=/path/to/private-key.pem"
+   ```
 
 ### Verify setup
 
@@ -199,7 +195,6 @@ Make sure the controller is running.
 kubectl -n argocd-commenter-system rollout status deployment argocd-commenter-controller-manager
 ```
 
-
 ## Configuration
 
 ### GitHub Enterprise Server
@@ -212,8 +207,6 @@ kubectl -n argocd-commenter-system create secret generic controller-manager \
   --from-literal="GITHUB_ENTERPRISE_URL=$YOUR_GITHUB_ENTERPRISE_URL"
 ```
 
-
 ## Contribution
 
 This is an open source software. Feel free to contribute to it.
-