docs/code-samples/eventing/gitlab-source/README.md

193 lines
5.2 KiB
Markdown

# GitLab source
GitLab Source example shows how to wire GitLab events for consumption by a
Knative Service.
## Gitlab source deployment
### Prerequisites
You will need:
1. An internet-accessible Kubernetes cluster with [Knative Serving](https://knative.dev/docs/install/serving/install-serving-with-yaml) installed.
1. Ensure Knative Serving is [configured with a domain name](https://knative.dev/docs/serving/using-a-custom-domain).
1. You must ensure that your Knative cluster uses a static IP address refer to your provider's documentation.
that allows GitLab to call into the cluster.
1. Install [Knative Eventing](https://knative.dev/docs/install/eventing/install-eventing-with-yaml).
### Install GitLab Event Source
GitLab Event source lives in the [knative-sandbox/eventing-gitlab](https://github.com/knative-sandbox/eventing-gitlab). Head to the releases page, find the latest release with `gitlab.yaml`
artifact and replace the `<RELEASE>` with version tag:
```bash
kubectl apply -f https://github.com/knative-sandbox/eventing-gitlab/releases/download/<RELEASE>/gitlab.yaml
```
Check that the manager is running:
```bash
kubectl -n knative-sources get pods --selector control-plane=gitlab-controller-manager
```
With the controller running you can now move on to a user persona and setup a
GitLab webhook as well as a function that will consume GitLab events.
## Using the GitLab Event Source
You are now ready to use the Event Source and trigger functions based on GitLab
projects events.
We will:
- Create a Knative service which will receive the events. To keep things simple
this service will simply dump the events to `stdout`, this is the so-called:
_event_display_
- Create a GitLab access token and a random secret token used to secure the
webhooks
- Create the event source by posting a GitLab source object manifest to
Kubernetes
### Create a Knative Service
The `event-display.yaml` file defines the basic service which will
receive events from the GitLab source:
```yaml
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
name: gitlab-event-display
spec:
template:
spec:
containers:
- image: gcr.io/knative-releases/knative.dev/eventing/cmd/event_display
```
Create the service:
```bash
kubectl -n default apply -f event-display.yaml
```
### Create GitLab Tokens
1. Create a
[personal access token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)
which the GitLab source will use to register webhooks with the GitLab API.
The token must have an "api" access scope in order to create repository
webhooks. Also decide on a secret token that your source will use to
authenticate the incoming webhooks from GitLab.
1. Update the secret values in `secret.yaml` as follows:
`accessToken` is the personal access token created in step 1 and
`secretToken` is any token of your choosing.
Tip: you can generate a random _secretToken_ by running the command:
```bash
head -c 8 /dev/urandom | base64
```
`secret.yaml`:
```yaml
apiVersion: v1
kind: Secret
metadata:
name: gitlabsecret
type: Opaque
stringData:
accessToken: <personal_access_token_value>
secretToken: <random_string>
```
1. Create the secret using `kubectl`.
```bash
kubectl -n default apply -f secret.yaml
```
### Create Event Source for GitLab Events
1. In order to receive GitLab events, you have to create a concrete Event Source
for a specific namespace. Replace the `projectUrl` value in the
`gitlabsource.yaml` file with your GitLab project URL, for example
`https://gitlab.com/knative-examples/functions`.
`gitlabsource.yaml`:
```yaml
apiVersion: sources.knative.dev/v1alpha1
kind: GitLabSource
metadata:
name: gitlabsource-sample
spec:
eventTypes:
- push_events
- issues_events
projectUrl: <project url>
accessToken:
secretKeyRef:
name: gitlabsecret
key: accessToken
secretToken:
secretKeyRef:
name: gitlabsecret
key: secretToken
sink:
ref:
apiVersion: serving.knative.dev/v1
kind: Service
name: gitlab-event-display
```
1. Apply the yaml file using `kubectl`:
```bash
kubectl -n default apply -f gitlabsource.yaml
```
### Verify
Verify that GitLab webhook was created by looking at the list of webhooks under
**Settings >> Integrations** in your GitLab project. A hook should be listed
that points to your Knative cluster.
Create a push event and check the logs of the Pod backing the
`gitlab-event-display` knative service. You will see the event:
```
☁️ cloudevents.Event
Validation: valid
Context Attributes,
specversion: 0.3
type: dev.knative.sources.gitlabsource.Push Hook
source: https://gitlab.com/<user>/<project>
id: f83c080f-c2af-48ff-8d8b-fd5b21c5938e
time: 2020-03-12T11:08:41.414572482Z
datacontenttype: application/json
Data,
{
<Event payload>
}
```
### Cleanup
You can remove the GitLab webhook by deleting the GitLab source:
```bash
kubectl --namespace default delete --filename gitlabsource.yaml
```
Similarly, you can remove the Service and Secret via:
```bash
kubectl --namespace default delete --filename event-display.yaml
kubectl --namespace default delete --filename secret.yaml
```