Add GitHub dispatch provider

api/v1beta1/provider_types.go

@@ -28,7 +28,7 @@ const (
 // ProviderSpec defines the desired state of Provider
 type ProviderSpec struct {
 	// Type of provider
-	// +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie;alertmanager;grafana;
+	// +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie;alertmanager;grafana;githubdispatch;
 	// +required
 	Type string `json:"type"`
 
@@ -69,25 +69,26 @@ type ProviderSpec struct {
 }
 
 const (
-	GenericProvider       string = "generic"
-	SlackProvider         string = "slack"
-	GrafanaProvider       string = "grafana"
-	DiscordProvider       string = "discord"
-	MSTeamsProvider       string = "msteams"
-	RocketProvider        string = "rocket"
-	GitHubProvider        string = "github"
-	GitLabProvider        string = "gitlab"
-	BitbucketProvider     string = "bitbucket"
-	AzureDevOpsProvider   string = "azuredevops"
-	GoogleChatProvider    string = "googlechat"
-	WebexProvider         string = "webex"
-	SentryProvider        string = "sentry"
-	AzureEventHubProvider string = "azureeventhub"
-	TelegramProvider      string = "telegram"
-	LarkProvider          string = "lark"
-	Matrix                string = "matrix"
-	OpsgenieProvider      string = "opsgenie"
-	AlertManagerProvider  string = "alertmanager"
+	GenericProvider        string = "generic"
+	SlackProvider          string = "slack"
+	GrafanaProvider        string = "grafana"
+	DiscordProvider        string = "discord"
+	MSTeamsProvider        string = "msteams"
+	RocketProvider         string = "rocket"
+	GitHubDispatchProvider string = "githubdispatch"
+	GitHubProvider         string = "github"
+	GitLabProvider         string = "gitlab"
+	BitbucketProvider      string = "bitbucket"
+	AzureDevOpsProvider    string = "azuredevops"
+	GoogleChatProvider     string = "googlechat"
+	WebexProvider          string = "webex"
+	SentryProvider         string = "sentry"
+	AzureEventHubProvider  string = "azureeventhub"
+	TelegramProvider       string = "telegram"
+	LarkProvider           string = "lark"
+	Matrix                 string = "matrix"
+	OpsgenieProvider       string = "opsgenie"
+	AlertManagerProvider   string = "alertmanager"
 )
 
 // ProviderStatus defines the observed state of Provider

config/crd/bases/notification.toolkit.fluxcd.io_providers.yaml

@@ -103,6 +103,7 @@ spec:
                 - opsgenie
                 - alertmanager
                 - grafana
+                - githubdispatch
                 type: string
               username:
                 description: Bot username for this provider

docs/spec/v1beta1/provider.md

@@ -9,7 +9,7 @@ Spec:
 ```go
 type ProviderSpec struct {
 	// Type of provider
-	// +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie
+	// +kubebuilder:validation:Enum=slack;discord;msteams;rocket;generic;github;gitlab;bitbucket;azuredevops;googlechat;webex;sentry;azureeventhub;telegram;lark;matrix;opsgenie;githubdispatch
 	// +required
 	Type string `json:"type"`
 
@@ -45,23 +45,24 @@ type ProviderSpec struct {
 
 Notification providers:
 
-| Provider        | Type          |
-| --------------- | ------------- |
-| Alertmanager    | alertmanager  |
-| Azure Event Hub | azureeventhub |
-| Discord         | discord       |
-| Generic webhook | generic       |
-| Google Chat     | googlechat    |
-| Grafana         | grafana       |
-| Lark            | lark          |
-| Matrix          | matrix        |
-| Microsoft Teams | msteams       |
-| Opsgenie        | opsgenie      |
-| Rocket          | rocket        |
-| Sentry          | sentry        |
-| Slack           | slack         |
-| Telegram        | telegram      |
-| WebEx           | webex         |
+| Provider        | Type           |
+| --------------- | -------------- |
+| Alertmanager    | alertmanager   |
+| Azure Event Hub | azureeventhub  |
+| Discord         | discord        |
+| Generic webhook | generic        |
+| GitHub dispatch | githubdispatch |
+| Google Chat     | googlechat     |
+| Grafana         | grafana        |
+| Lark            | lark           |
+| Matrix          | matrix         |
+| Microsoft Teams | msteams        |
+| Opsgenie        | opsgenie       |
+| Rocket          | rocket         |
+| Sentry          | sentry         |
+| Slack           | slack          |
+| Telegram        | telegram       |
+| WebEx           | webex          |
 
 Git commit status providers:
 
@@ -123,7 +124,8 @@ kubectl create secret generic webhook-url \
 Note that the secret must contain an `address` field.
 
 The provider type can be: `slack`, `msteams`, `rocket`, `discord`, `googlechat`, `webex`, `sentry`,
-`telegram`, `lark`, `matrix`, `azureeventhub`, `opsgenie`, `alertmanager`, `grafana` or `generic`.
+`telegram`, `lark`, `matrix`, `azureeventhub`, `opsgenie`, `alertmanager`, `grafana`,
+`githubdispatch` or `generic`.
 
 Some networks need to use an authenticated proxy to access external services. Therefore, the authentication can be stored as a secret to hide parameters like the username and password.
 
@@ -730,3 +732,141 @@ kubectl create secret generic webhook-url \
 --from-literal=address="Endpoint=sb://fluxv2.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=yoursaskeygeneatedbyazure"
 ```
 
+### GitHub repository dispatch
+
+The `githubdispatch` provider generates GitHub events of type [`repository_dispatch`](https://docs.github.com/en/rest/reference/repos#create-a-repository-dispatch-event) for the selected repository. The `repository_dispatch` events can be used to trigger GitHub Actions workflow.
+
+The request includes the `event_type` and `client_payload` fields:
+
+* The `event_type` is generated by GitHub Dispatch provider by combining the Kind, Name and Namespace of the involved object in the format `{Kind}/{Name}.{Namespace}`. For example, the `event_type` for a Flux Kustomization named `podinfo` in the `flux-system` namespace looks like this: `Kustomization/podinfo.flux-system`.
+
+* The `client_payload` contains the Kubernetes event issued by Flux, e.g.:
+
+```yaml
+{
+  involvedObject: {
+    apiVersion: kustomize.toolkit.fluxcd.io/v1beta2,
+    kind: Kustomization,
+    name: podinfo,
+    namespace: flux-system,
+    resourceVersion: 426573,
+    uid: b9b8554d-be26-4a3d-a97f-65f3276a097a
+  },
+  message: Deployment/podinfo/podinfo configured,
+  metadata: {
+    revision: main/96139968ca46b53462d1bf94de410a811d2026a1,
+    summary: "staging (us-west-2)"
+  },
+  reason: Progressing,
+  reportingController: kustomize-controller,
+  reportingInstance: kustomize-controller-79464d8dc5-nb9c4,
+  severity: info,
+  timestamp: 2022-04-20T12:20:28Z
+}
+```
+
+### Setting up the GitHub dispatch provider
+
+```yaml
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Provider
+metadata:
+  name: github-dispatch
+  namespace: flux-system
+spec:
+  type: githubdispatch
+  address: https://github.com/stefanprodan/podinfo
+  secretRef:
+    name: api-token
+```
+
+The `address` is the address of your repository where you want to send webhooks to trigger GitHub workflows.
+
+GitHub uses personal access tokens for authentication with its API:
+
+* [GitHub personal access token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/creating-a-personal-access-token)
+
+The provider requires a secret in the same format, with the personal access token as the value for the token key:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: api-token
+  namespace: default
+data:
+  token: <personal-access-tokens>
+```
+
+#### Setting up a GitHub workflow
+
+To trigger a GitHub Actions workflow when a Flux Kustomization finishes reconciling, you need to set the event type for the repository_dispatch trigger to match the Flux object ID:
+
+```yaml
+name: test-github-dispatch-provider
+on:
+  repository_dispatch:
+    types: [Kustomization/podinfo.flux-system]
+```
+
+Assuming that we deploy all Flux kustomization resources in the same namespace, it will be useful to have a unique kustomization resource name for each application. This will allow you to use only `event_type` to trigger tests for the exact application.
+
+Let's say we have following folder structure for applications kustomization manifests:
+
+```bash
+apps/
+├── app1
+│   └── overlays
+│       ├── production
+│       └── staging
+└── app2
+    └── overlays
+        ├── production
+        └── staging
+```
+
+You can then create a flux kustomization resource for the app to have unique `event_type` per app. The kustomization manifest for app1/staging:
+
+```yaml
+apiVersion: kustomize.toolkit.fluxcd.io/v1beta2
+kind: Kustomization
+metadata:
+  name: app1
+  namespace: flux-system
+  spec:
+    path: "./app1/staging"
+```
+
+You would also like to know from the notification which cluster is being used for deployment. You can add the `spec.summary` field to the Flux alert configuration to mention the relevant cluster:
+
+```yaml
+apiVersion: notification.toolkit.fluxcd.io/v1beta1
+kind: Alert
+metadata:
+  name: github-dispatch
+  namespace: flux-system
+spec:
+  summary: "staging (us-west-2)"
+  providerRef:
+    name: github-dispatch
+  eventSeverity: info
+  eventSources:
+    - kind: Kustomization
+      name: 'podinfo'
+```
+
+Now you can the trigger tests in the GitHub workflow for app1 in a staging cluster when the app1 resources defined in `./app1/staging/` are reconciled by Flux:
+
+```yaml
+name: test-github-dispatch-provider
+on:
+  repository_dispatch:
+    types: [Kustomization/podinfo.flux-system]
+jobs:
+  run-tests-staging:
+    if: github.event.client_payload.metadata.summary == 'staging (us-west-2)'
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Run tests
+      run: echo "running tests.."
+```

internal/notifier/factory.go

@@ -67,6 +67,8 @@ func (f Factory) Notifier(provider string) (Interface, error) {
 		n, err = NewMSTeams(f.URL, f.ProxyURL, f.CertPool)
 	case v1beta1.GitHubProvider:
 		n, err = NewGitHub(f.URL, f.Token, f.CertPool)
+	case v1beta1.GitHubDispatchProvider:
+		n, err = NewGitHubDispatch(f.URL, f.Token, f.CertPool)
 	case v1beta1.GitLabProvider:
 		n, err = NewGitLab(f.URL, f.Token, f.CertPool)
 	case v1beta1.BitbucketProvider:

internal/notifier/github_dispatch.go

@@ -0,0 +1,121 @@
+/*
+Copyright 2022 The Flux authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package notifier
+
+import (
+	"context"
+	"crypto/tls"
+	"crypto/x509"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+
+	"github.com/fluxcd/pkg/runtime/events"
+
+	"github.com/google/go-github/v41/github"
+	"golang.org/x/oauth2"
+)
+
+type GitHubDispatch struct {
+	Owner  string
+	Repo   string
+	Client *github.Client
+}
+
+func NewGitHubDispatch(addr string, token string, certPool *x509.CertPool) (*GitHubDispatch, error) {
+	if len(token) == 0 {
+		return nil, errors.New("github token cannot be empty")
+	}
+
+	host, id, err := parseGitAddress(addr)
+	if err != nil {
+		return nil, err
+	}
+
+	baseUrl, err := url.Parse(host)
+	if err != nil {
+		return nil, err
+	}
+
+	comp := strings.Split(id, "/")
+	if len(comp) != 2 {
+		return nil, fmt.Errorf("invalid repository id %q", id)
+	}
+
+	ts := oauth2.StaticTokenSource(&oauth2.Token{AccessToken: token})
+	tc := oauth2.NewClient(context.Background(), ts)
+	client := github.NewClient(tc)
+	if baseUrl.Host != "github.com" {
+		if certPool != nil {
+			tr := &http.Transport{
+				TLSClientConfig: &tls.Config{
+					RootCAs: certPool,
+				},
+			}
+			hc := &http.Client{Transport: tr}
+			ctx := context.WithValue(context.Background(), oauth2.HTTPClient, hc)
+			tc = oauth2.NewClient(ctx, ts)
+		}
+
+		client, err = github.NewEnterpriseClient(host, host, tc)
+		if err != nil {
+			return nil, fmt.Errorf("could not create enterprise GitHub client: %v", err)
+		}
+	}
+
+	return &GitHubDispatch{
+		Owner:  comp[0],
+		Repo:   comp[1],
+		Client: client,
+	}, nil
+}
+
+// Post GitHub Repository Dispatch webhook
+func (g *GitHubDispatch) Post(event events.Event) error {
+	// Skip any update events
+	if isCommitStatus(event.Metadata, "update") {
+		return nil
+	}
+
+	eventType := fmt.Sprintf("%s/%s.%s",
+		event.InvolvedObject.Kind, event.InvolvedObject.Name, event.InvolvedObject.Namespace)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
+	defer cancel()
+
+	eventData, err := json.Marshal(event)
+	if err != nil {
+		return fmt.Errorf("Failed to marshal object into json: %w", err)
+	}
+	eventDataRaw := json.RawMessage(eventData)
+
+	opts := github.DispatchRequestOptions{
+		EventType:     eventType,
+		ClientPayload: &eventDataRaw,
+	}
+	_, _, err = g.Client.Repositories.Dispatch(ctx, g.Owner, g.Repo, opts)
+
+	if err != nil {
+		return fmt.Errorf("Could not send github repository dispatch webhook: %v", err)
+	}
+
+	return nil
+}