From edddf65d0ee4a1ac4e99c546cc918d7674527840 Mon Sep 17 00:00:00 2001 From: Philip Laine Date: Mon, 21 Sep 2020 23:02:14 +0200 Subject: [PATCH] Update docs for git notifiers --- docs/diagrams/gitlab-commit-status.png | Bin 0 -> 3435 bytes docs/guides/notifications.md | 40 ++++++++++++++++++------- 2 files changed, 29 insertions(+), 11 deletions(-) create mode 100644 docs/diagrams/gitlab-commit-status.png diff --git a/docs/diagrams/gitlab-commit-status.png b/docs/diagrams/gitlab-commit-status.png new file mode 100644 index 0000000000000000000000000000000000000000..9319725f63fac04f912d0e9f052fe70013202398 GIT binary patch literal 3435 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 N002ovPDHLkV1f{&s3ZUY literal 0 HcmV?d00001 diff --git a/docs/guides/notifications.md b/docs/guides/notifications.md index e1ff1629..216aaadb 100644 --- a/docs/guides/notifications.md +++ b/docs/guides/notifications.md @@ -45,7 +45,7 @@ spec: name: slack-url ``` -The provider type can be `slack`, `msteams`, `discord`, `rocket` or `generic`. +The provider type can be `slack`, `msteams`, `discord`, `rocket`, `github`, `gitlab` or `generic`. When type `generic` is specified, the notification controller will post the incoming [event](../components/notification/event.md) in JSON format to the webhook address. @@ -103,19 +103,39 @@ When the verbosity is set to `info`, the controller will alert if: ![info alert](../diagrams/slack-info-alert.png) -## GitHub commit status +## Git commit status -The GitHub provider is a special kind of notification provider that based on the -state of a Kustomization resource, will update the -[commit status](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks) for the currently reconciled commit id. +The `github` and `gitlab` provider are slightly different to the other chat providers. These providers will +link an event back to its source by writing a commit status event to the repository. For more information about how a +commit status works, refer to the [GitHub](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks) +or [GitLab](https://docs.gitlab.com/ee/api/commits.html) documentation. -The resulting status will contain information from the event in the format `{{ .Kind }}/{{ .Name }} - {{ .Reason }}`. +The first image is an example of how it may look like in GitHub while the one below is an example for GitLab. ![github commit status](../diagrams/github-commit-status.png) +![gitlab commit status](../diagrams/gitlab-commit-status.png) -It is important to note that the referenced provider needs to refer to the -same GitHub repository as the Kustomization originates from. If these do -not match the notification will fail as the commit id will not be present. +Currently the provider will only work with Alerts for Kustomization resources as the events have to be linked with a +specific git commit. Any other event that does not contain a commit reference will be ignored by the provider. +Each status will contain some additional information from the event which includes the resource kind, name and reason for the event. +It will be displayed in the format of `{{ .Kind }}/{{ .Name }} - {{ .Reason }}`. +To get started the git provider require an authentication token to communicate with the API. +Follow the [GitHub](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) +or [Gitlab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for a detailed guide how to create a token. +Store the generated token in a Secret with the following data format. +```yaml +apiVersion: v1 +kind: Secret +metadata: + name: github + namespace: gitops-system +data: + token: +``` + +Creating a git provider is very similar to creating other types of providers. +The only caveat being that the provider address needs to point to the same +git repository as the Kustomization resource refers to. ```yaml apiVersion: notification.toolkit.fluxcd.io/v1alpha1 kind: Provider @@ -155,5 +175,3 @@ metadata: data: token: ``` - -