GitHub source

GitHub Source example shows how to wire GitHub events for consumption by a Knative Service.

Deployment Steps

Prerequisites

You will need:

  1. An internet-accessible Kubernetes cluster with Knative Serving installed. Follow the installation instructions if you need to create one.
  2. Ensure Knative Serving is configured with a domain name that allows GitHub to call into the cluster.
  3. If you’re using GKE, you’ll also want to assign a static IP address.
  4. Install Knative Eventing. Those instructions also install the default eventing sources, including the GitHubSource we’ll use.

Install Github Event Source

Github Event source lives in the knative/eventing-contrib. You can install it by running the following (this is currently the latest released version (0.11.2))

  1. kubectl apply -f https://github.com/knative/eventing-contrib/releases/download/v0.15.0/github.yaml

Create a Knative Service

To verify the GitHubSource is working, we will create a simple Knative Service that dumps incoming messages to its log. The service.yaml file defines this basic service.

  1. apiVersion: serving.knative.dev/v1
  2. kind: Service
  3. metadata:
  4.   name: github-message-dumper
  5. spec:
  6.   template:
  7.     spec:
  8.       containers:
  9.       - image: gcr.io/knative-releases/knative.dev/eventing-contrib/cmd/event_display

Enter the following command to create the service from service.yaml:

  1. kubectl --namespace default apply --filename service.yaml

Create GitHub Tokens

Create a personal access token for GitHub that the GitHub source can use to register webhooks with the GitHub API. Also decide on a secret token that your code will use to authenticate the incoming webhooks from GitHub (secretToken).

The token can be named anything you find convenient. The Source requires repo:public_repo and admin:repo_hook, to let it fire events from your public repositories and to create webhooks for those repositories. Copy and save this token; GitHub will force you to generate it again if misplaced.

Here’s an example for a token named “GitHubSource Sample” with the recommended scopes:

GitHub UI

Update githubsecret.yaml with those values. If your generated access token is 'personal_access_token_value' and you choose your secretToken as 'asdfasfdsaf', you’d modify githubsecret.yaml like so:

  1. apiVersion: v1
  2. kind: Secret
  3. metadata:
  4.   name: githubsecret
  5. type: Opaque
  6. stringData:
  7.   accessToken: personal_access_token_value
  8.   secretToken: asdfasfdsaf

Hint: you can makeup a random secretToken with:

  1. head -c 8 /dev/urandom | base64

Then, apply the githubsecret using kubectl:

  1. kubectl --namespace default apply --filename githubsecret.yaml

Create Event Source for GitHub Events

In order to receive GitHub events, you have to create a concrete Event Source for a specific namespace. Be sure to replace the ownerAndRepository value with a valid GitHub public repository owned by your GitHub user.

If using GitHub enterprise you will need to add an additional githubAPIURL field to the spec specifying your GitHub enterprise API endpoint, see here

  1. apiVersion: sources.knative.dev/v1alpha1
  2. kind: GitHubSource
  3. metadata:
  4.   name: githubsourcesample
  5. spec:
  6.   eventTypes:
  7.     - pull_request
  8.   ownerAndRepository: <YOUR USER>/<YOUR REPO>
  9.   accessToken:
  10.     secretKeyRef:
  11.       name: githubsecret
  12.       key: accessToken
  13.   secretToken:
  14.     secretKeyRef:
  15.       name: githubsecret
  16.       key: secretToken
  17.   sink:
  18.     ref:
  19.       apiVersion: serving.knative.dev/v1
  20.       kind: Service
  21.       name: github-message-dumper

Then, apply that yaml using kubectl:

  1. kubectl --namespace default apply --filename github-source.yaml

Verify

Verify the GitHub webhook was created by looking at the list of webhooks under the Settings tab in your GitHub repository. A hook should be listed that points to your Knative cluster with a green check mark to the left of the hook URL, as shown below.

GitHub Webhook

Create Events

Create a pull request in your GitHub repository. We will verify that the GitHub events were sent into the Knative eventing system by looking at our message dumper function logs.

  1. kubectl --namespace default get pods
  2. kubectl --namespace default logs github-event-display-XXXX user-container

You should log lines similar to:

  1. 2018/11/08 18:25:34 Message Dumper received a message: POST / HTTP/1.1
  2. Host: github-event-display.knative-demo.svc.cluster.local
  3. Accept-Encoding: gzip
  4. Ce-Cloudeventsversion: 0.1
  5. Ce-Eventid: a8d4cf20-e383-11e8-8069-46e3c8ad2b4d
  6. Ce-Eventtime: 2018-11-08T18:25:32.819548012Z
  7. Ce-Eventtype: dev.knative.source.github.pull_request
  8. Ce-Source: https://github.com/someuser/somerepo/pull/1
  9. Content-Length: 21060
  10. Content-Type: application/json
  11. User-Agent: Go-http-client/1.1
  12. X-B3-Parentspanid: b2e514c3dbe94c03
  13. X-B3-Sampled: 1
  14. X-B3-Spanid: c85e346d89c8be4e
  15. X-B3-Traceid: abf6292d458fb8e7
  16. X-Envoy-Expected-Rq-Timeout-Ms: 60000
  17. X-Envoy-Internal: true
  18. X-Forwarded-For: 127.0.0.1, 127.0.0.1
  19. X-Forwarded-Proto: http
  20. X-Request-Id: 8a2201af-5075-9447-b593-ec3a243aff52
  22. {"action":"opened","number":1,"pull_request": ...}

Cleanup

You can remove the Github webhook by deleting the Github source:

  1. kubectl --namespace default delete --filename github-source.yaml

Similarly, you can remove the Service and Secret via:

  1. kubectl --namespace default delete --filename service.yaml
  2. kubectl --namespace default delete --filename githubsecret.yaml