notification-controller/docs/spec/v1beta2/statusupdates.md

Git Commit Status Updates

The notification-controller can mark Git commits as reconciled by posting Flux Kustomization events to the origin repository using Git SaaS providers APIs.

Example

The following is an example of how to update the Git commit status for the GitHub repository where Flux was bootstrapped with flux bootstrap github --owner=my-gh-org --repository=my-gh-repo.

apiVersion: notification.toolkit.fluxcd.io/v1beta2
kind: Provider
metadata:
  name: github-status
  namespace: flux-system
spec:
  type: github
  address: https://github.com/my-gh-org/my-gh-repo
  secretRef:
    name: github-token
---
apiVersion: notification.toolkit.fluxcd.io/v1beta2
kind: Alert
metadata:
  name: github-status
  namespace: flux-system
spec:
  providerRef:
    name: github-status
  eventSources:
    - kind: Kustomization
      name: flux-system

In the above example:

• A Provider named github-status is created, indicated by the Provider.metadata.name field.
• An Alert named github-status is created, indicated by the Alert.metadata.name field.
• The Alert references the GitHub provider, indicated by the Alert.spec.providerRef field.
• The notification-controller starts listening for events sent by the flux-system Kustomization.
• When an event is received, the controller extracts the Git commit SHA from the event payload.
• The controller uses the GitHub PAT from the secret indicated by the Provider.spec.secretRef.name to authenticate with the GitHub API.
• The controller sets the commit status to kustomization/flux-system/<UID> followed by the success or error message from the event body.

Writing a Git commit status provider spec

As with all other Kubernetes config, a Provider needs apiVersion, kind, and metadata fields. The name of an Alert object must be a valid DNS subdomain name. A Provider also needs a .spec section.

Type

.spec.type is a required field that specifies which Git SaaS vendor hosts the repository.

The supported types are: github, gitlab, bitbucket and azuredevops.

Address

.spec.address is a required field that specifies the HTTPS URL of the Git repository where the commits originate from.

Secret reference

.spec.secretRef.name is a required field to specify a name reference to a Secret in the same namespace as the Provider, containing the authentication credentials for the Git SaaS API.

GitHub authentication

When .spec.type is set to github, the referenced secret must contain a key called token with the value set to a GitHub personal access token.

The token must has permissions to update the commit status for the GitHub repository specified in .spec.address.

You can create the secret with kubectl like this:

kubectl create secret generic github-token --from-literal=token=<GITHUB-TOKEN>

GitLab authentication

When .spec.type is set to gitlab, the referenced secret must contain a key called token with the value set to a GitLab personal access token.

The token must has permissions to update the commit status for the GitLab repository specified in .spec.address.

You can create the secret with kubectl like this:

kubectl create secret generic gitlab-token --from-literal=token=<GITLAB-TOKEN>

BitBucket authentication

When .spec.type is set to bitbucket, the referenced secret must contain a key called token with the value set to a BitBucket username and an app password in the format <username>:<app-password>.

The app password must have Repositories (Read/Write) permission for the BitBucket repository specified in .spec.address.

You can create the secret with kubectl like this:

kubectl create secret generic gitlab-token --from-literal=token=<username>:<app-password>

Azure DevOps authentication

When .spec.type is set to azuredevops, the referenced secret must contain a key called token with the value set to a Azure DevOps personal access token.

The token must has permissions to update the commit status for the Azure DevOps repository specified in .spec.address.

You can create the secret with kubectl like this:

kubectl create secret generic github-token --from-literal=token=<AZURE-TOKEN>

Suspend

.spec.suspend is an optional field to suspend the Git commit status updates. When set to true, the controller will stop processing events for this provider. When the field is set to false or removed, it will resume the commit status updates.