argocd-commenter

README

argocd-commenter

This is a Kubernetes Controller to notify a change of Argo CD Application status.

Example: Pull Request notification

In the GitOps way, you merge a pull request to deploy a change to Kubernetes cluster. argocd-commenter allows you to receive a notification after merge.

When an Application is syncing, synced or healthy, argocd-commenter creates a comment. It determines a pull request from revision of Application.

When the sync was failed, argocd-commenter creates a comment.

See the examples in e2e test fixtures.

Example: GitHub Deployment notification

In a complex deployment flow, you can receive a notification using GitHub Deployments API. For example, if you deploy a preview environment for a pull request, you can receive notifications via GitHub Deployment.

You need to create a Deployment to receive notifications. If an Application contains the following annotation,

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:

Here is an example of workflow to deploy a preview environment:

jobs:
  deploy:
        steps:
      # create a deployment
      - uses: int128/deployment-action@v1
        id: deployment

      # generate manifests for preview environment
      - uses: actions/checkout@v2
        with:
          repository: your/manifests-repository
          path: manifests-repository
          token: # PAT or GitHub App token is required to write
      - run: |
          cp -a manifests "manifests-repository/pr-${{ github.event.pull_request.number }}"
          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
      - run: |
          git add .
          git commit -m 'Deploy pr-${{ github.event.pull_request.number }}'
          git push manifests-repository main

See the e2e test for details.

Getting Started

Prerequisite

Argo CD is running in your Kubernetes cluster.

Setup

To deploy the manifest:

kubectl apply -f https://github.com/int128/argocd-commenter/releases/download/v0.3.0/argocd-commenter.yaml

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
• GitHub App
  • Belong to a user or organization
  • Have each rate limit for an installation

Option 1: Personal Access Token

1. Open https://github.com/settings/tokens
2. Generate a new token
3. Create a secret as follows:

   kubectl -n argocd-commenter-system create secret generic controller-manager \
     --from-literal="GITHUB_TOKEN=$YOUR_PERSONAL_ACCESS_TOKEN"
   

Option 2: 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)
2. Get the App ID from the setting page
3. Download a private key of the GitHub App
4. Set a custom badge for the GitHub App
   • Logo of Argo CD is available in CNCF Branding
5. Install your GitHub App on your repository or organization
6. Get the Installation ID from the URL, like https://github.com/settings/installations/ID
7. Create a secret as follows:

   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

Make sure the controller is running.

kubectl -n argocd-commenter-system rollout status deployment argocd-commenter-controller-manager

Contribution

This is an open source software. Feel free to contribute to it.