From 361068674b8a7fb7143508759d34f083fb9d0261 Mon Sep 17 00:00:00 2001 From: Hidetake Iwata Date: Sun, 18 Feb 2024 18:05:51 +0900 Subject: [PATCH] Update README.md --- README.md | 85 +++++++++++++++++++++++++------------------------------ 1 file changed, 39 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index e94e5f56..6a91bd4d 100644 --- 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) +image -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) +image -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. -