flux2/docs/guides/commit-notifications.md

Commit based Notifications

The GitHub, GitLab, Bitbucket, and Azure DevOps providers are slightly different to the other providers. Instead of a stateless stream of events, the git notification providers will link the event with accompanying git commit which triggered the event. The linking is done by updating the commit status of a specific commit.

• GitHub
• GitLab
• Bitbucket
• Azure DevOps

In GitHub the commit status set by notification-controller will result in a green checkmark or red cross next to the commit hash. Clicking the icon will show more detailed information about the status.

Receiving an event in the form of a commit status has the benefit that it closes the deployment loop. This gives quick and visible feedback if a commit has reconciled and if it succeeded. This means deployments operate in a similar manner to "traditional" push based CD. Status can be fetched from the git providers API for a specific commit. This allows for custom automation tools that can automatically promote, commit to a new directory, after receiving a successful commit status. This can all be done without requiring any access to the Kubernetes cluster

The provider works by referencing the same git repository as the Kustomization controller does. When a new commit is pushed to the repository, source-controller will sync the commit, triggering the kustomize-controller to reconcile the new commit. After this is done the kustomize-controller sends an event to the notification-controller with the result and the commit hash it reconciled. Then notification-controller can update the correct commit and repository when receiving the event.

!!! hint "Limitations" The git notification providers require that a commit hash present in the meta data of the event. There for the the providers will only work with Kustomization as an event source, as it is the only resource which includes this data.

Prerequisites

Authentication Token

Obtaining your git providers credentials

The token/app-password will need to have write access for the repository it will be updating the commit status in.

Follow the respective guide for your git provider

• GitHub personal access token
• GitLab personal access token
• Azure DevOps personal access token
• app password

Creating Git Secret for your token/app-password

Use the following command to store the token/app-password in a secret

=== "GitHub, GitLab, Azure DevOps" bash $ kubectl -n flux-system create secret generic git \ --from-literal=token='<YOURTOKEN>' --- apiVersion: v1 data: token: PFlPVVJUT0tFTj4= kind: Secret metadata: creationTimestamp: null name: git namespace: flux-system === "BitBucket" bash $ kubectl -n flux-system create secret generic bitbucket\ --from-literal=token='<username>:<app-password>' --- apiVersion: v1 kind: Secret metadata: name: git namespace: default data: token: <username>:<app-password>

Creating a Deployment

Copy the manifest content in the "kustomize" directory into the directory "./clusters/my-cluster/podinfo" in your fleet-infra repository. Make sure that you also add the namespace podinfo.

apiVersion: v1
kind: Namespace
metadata:
  name: podinfo

Then create a Kustomization to deploy podinfo.

apiVersion: kustomize.toolkit.fluxcd.io/v1beta1
kind: Kustomization
metadata:
  name: podinfo
  namespace: flux-system
spec:
  interval: 5m
  targetNamespace: podinfo
  path: ./clusters/my-cluster/podinfo
  prune: true
  sourceRef:
    kind: GitRepository
    name: flux-system
  healthChecks:
    - apiVersion: apps/v1
      kind: Deployment
      name: podinfo
      namespace: podinfo
  timeout: 1m

Creating the Git provider

Creating a git provider is similar to creating other providers. The only difference is that with git providers spec.address needs to point to the same git repository that the event source originates from.

=== "GitHub" yaml apiVersion: notification.toolkit.fluxcd.io/v1beta1 kind: Provider metadata: name: flux-system namespace: flux-system spec: type: github address: https://github.com/<username>/fleet-infra secretRef: name: git

=== "GitLab" yaml apiVersion: notification.toolkit.fluxcd.io/v1beta1 kind: Provider metadata: name: flux-system namespace: flux-system spec: type: gitlab address: https://gitlab.com/<username>/fleet-infra secretRef: name: git === "Bitbucket" bash === "Azure DevOps" bash

Creating the alert

=== "GitHub" bash $ flux create alert podinfo \ --provider-ref git \ --event-severity info \ --event-source 'Kustomization/podinfo' \ --namespace 'flux-system' \ --export --- apiVersion: notification.toolkit.fluxcd.io/v1beta1 kind: Alert metadata: name: podinfo namespace: flux-system spec: providerRef: name: flux-system eventSeverity: info eventSources: - kind: Kustomization name: podinfo namespace: flux-system === "GitLab" bash === "Bitbucket" bash === "Azure DevOps" bash

By now the fleet-infra repository should have a similar directory structure.

fleet-infra
└── clusters/
    └── my-cluster/
        ├── flux-system/
        │   ├── gotk-components.yaml
        │   ├── gotk-sync.yaml
        │   └── kustomization.yaml
        ├── podinfo/
        │   ├── namespace.yaml
        │   ├── deployment.yaml
        │   ├── hpa.yaml
        │   ├── service.yaml
        │   └── kustomization.yaml
        ├── podinfo-kustomization.yaml
        └── podinfo-notification.yaml

If podinfo is deployed and the health checks pass you should get a successful status in your forked podinfo repository.

If everything is setup correctly there should now be a green check-mark next to the latest commit. Clicking the check-mark should show a detailed view.

=== "Github" === "GitLab" |

Generate an error

A deployment failure can be forced by setting an invalid image tag in the podinfo deployment.

apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: podinfod
        image: ghcr.io/stefanprodan/podinfo:fake

After the commit has been reconciled it should return a failed commit status.

=== "GitHub" === "GitLab" |