mirror of https://github.com/knative/docs.git
193 lines
5.2 KiB
Markdown
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
|
|
|
|
```
|