Deploying a Github Sensor

This guide will walk through the steps to install and configure a Github sensor deployment to collect metrics from github and publish the metrics to the client tenant running in cloud.

Pre-Requisites

Follow the guide for Common Pre-requisites to complete the pre-requisites for deploying a sensor.

How it works

The Github sensor collects data from Github using the provided access token and then sends it to the configured stream. The sensor is triggered based on a specified cron-style schedule.

Github Token

To configure the Github sensor, the user needs to provide the sensor specification as a Kubernetes custom resource definition (CRD) and create a secret with the access token generated from Github. The user can then deploy the sensor on the Kubernetes cluster.

The secret created to store the token must be created like this:

kind: Secret
apiVersion: v1
metadata:
  name: <secret-name>
  namespace: <sample_tenant>
data:
  token: <redacted base64 string of pat token>

To ensure the token is properly encoded in base64, you can use the following command:

echo -n "your-github-access-token" | base64

Replace "your-github-access-token" with your actual Github access token.

Custom Host

By default api.github.com is used as host and uploads.github.com is used as upload url. If you need to use your own host and upload url you will need to specify:

data:
  host: "personal-host"
  uploadUrl: "personal-uploadUrl"

Repo Groups

The Github sensor requires an array of repoGroups to be configured in order to collect data. The configuration for each repoGroup looks like this:

data:
  repoGroups:
    - owner: "owner"
      metrics:
        - "metric-name-1"
        - "metric-name-2"
      repos:
        - "*" # to get all repos or...
        - "repo-name-1"
        - "repo-name-2"

When the sensor is triggered, it retrieves the desired data for each repo in the array of repoGroups, generating a new signal for each specified metric. The retrieved data is then packaged as a signal and sent to the configured stream, where it can be analyzed and processed by the Fitness Functions.

Metrics

There are various metrics that can be collected using Orcasio's Github sensor, and these can be specified in the metrics field.

By default, information about the project is included in all signals. This information can be checked in: https://docs.github.com/en/rest/repos#get-a-repository

The possible metrics are:

Configuration

Copy the following yml file and make changes for all the TODO sections.

kind: FitnessSensor
apiVersion: fitness.orcasio.com/v1alpha3
metadata:
  ## TODO: name of the sensor
  name: <sensor-name>
  namespace: <tenant_ID>
spec:
  sensor: sensor://fitness.orcasio.net/github
  source: github
  enabled: true
  secret: <secrets_name>    
  trigger:
    name: cron
    cron:
      ## TODO - every 5 minutes
      schedule: "0 0/5 * * * *"
  data:
    host: api.github.com
    uploadHost: uploads.github.com
    repoGroups:
      ## TODO: metrics and repos
      - owner: "owner"
        metrics:
          - "action-name1"
          - "action-name2"
        repos:
          - "repo1"
          - "repo2"

Github Sensor configuration

As shown in the sample the configuration for a Github Fitness Sensor is done using a Kubernetes CRD object. This specification is picked up by the Pulse Sensor Deployment and the deployment runs the sensor on a time basis to fetch the data and publish to the remote tenant as a stream over HTTP.

Sensor Specification

Deploy Custom Sensor Specification

Create the FitnessSensor object defining the sensor configuration for the Custom Rest API Sensor. The FitnessSensor object needs to replace the last section of the file below

## TODO - CHANGE THE SAMPLE BELOW AS NEEDED
## CUSTOM SENSOR CONFIG
kind: FitnessSensor
apiVersion: fitness.orcasio.com/v1alpha3
metadata:
  name: turtles-all-the-way
  namespace: <tenant_ID>
spec:
  sensor: sensor://fitness.orcasio.net/github
  source: github
  ## TODO - secret name with token
  secret: <secret_name>
  enabled: true
  ## TODO - cron for every 5 minutes
  trigger:
    name: cron
    cron:
      schedule: "0 * * * * *"
  data:
  ## TODO - change repo groups as needed
    host: api.github.com
    repoGroups:
      - owner: <owner>
        metrics:
          - <metric_name>
        repos:
          - <repo_name>
  tags:
    env: dev
    org: it

Once all other TODOs in the file are completed the configuration can be applied to a Kubernetes cluster

kubectl -n <tenant-id> apply -f <filename.yaml>

Examples

apiVersion: fitness.orcasio.com/v1alpha3
kind: FitnessSensor
spec:
  sensor: sensor://fitness.orcasio.net/github
  source: github
  tenant: sample_tenant
  secret: github
  tags:
    foo: bar
  trigger:
    cron:
      schedule: 0 0 0 * * *
    name: cron
  enabled: true
  data:
    repoGroups:
      - owner: sampleOrg
        metrics:
          - workflows
        repos:
          - "*"

kind: Secret
apiVersion: v1
metadata:
  name: github
  namespace: orcas
data:
  token: encodedTokenInBase64

apiVersion: fitness.orcasio.com/v1alpha3
kind: FitnessSensor
spec:
  sensor: sensor://fitness.orcasio.net/github
  source: github
  tenant: sample_tenant
  secret: github
  tags:
    foo: bar
  trigger:
    cron:
      schedule: 0 0 0/12 * * *
    name: cron
  enabled: true
  data:
    repoGroups:
      - owner: sampleOrg
        metrics:
          - workflows
          - dependabot
        repos:
          - "repo1"
      - "repo2"