Skip to content

README.md

Latest commit

 

History

History
167 lines (137 loc) · 8.01 KB

README.md

File metadata and controls

167 lines (137 loc) · 8.01 KB

GITHUB RECEIVER PLUGIN

The Github Receiver Plugin is used to receive webhook events from github and store them in the database for the Github Handler Plugin to pick up and process.

What you need:

  1. An active database the receiver can access. For help setting up the database, see Database Setup. It needs to be the same database as the Github Handler Plugin.
  2. Some sort of Auth method like a PAT or a Github App for the repo you want to receive webhooks for. They need:
  • Repo Receiver: Administration, Webhooks, and Actions set to Read and write.
  • Org Receiver: Under Organization permissions set Administration, Webhooks, and Self-hosted runners to Read and write.
  • IMPORTANT: Make sure to check your email to verify any permission requests.
  1. A way to receive webhooks. This can be a public URL or IP that points to the server running the Anklet Github Receiver. Github will send the webhook to this endpoint over the internet.

In the config.yml, you can define the github_receiver plugin as follows:

NOTE: Plugin name MUST be unique across all hosts and plugins in your Anklet cluster.

---

. . .

global_receiver_secret: 12345 # this can be set using the ANKLET_GLOBAL_RECEIVER_SECRET env var too
plugins:
  - name: GITHUB_WEBHOOK_RECEIVER_1
    plugin: github_receiver
    hook_id: 4897477123
    port: 54321
    # secret: 12345
    token: github_pat_XXX
    # private_key: /Users/{YOUR USER HERE}/private-key.pem
    app_id: 949431
    installation_id: 52970581
    # repo: anklet # Optional; if you want to receive webhooks for a specific repo and not at the org level
    owner: veertuinc
    # queue_name: shared_queue # Optional; override the queue namespace (defaults to owner). Useful for multiple orgs sharing a queue.
    # skip_redeliver: true # Optional; if you want to skip redelivering undelivered webhooks on startup
    # redeliver_hours: 24 # Optional; default is 24 hours
    #database:
    #  url: localhost
    #  port: 6379
    #  user: ""
    #  password: ""
    #  database: 0

Some things to note:

  • If you leave off repo, the receiver will be an organization level receiver.
  • The receiver must come FIRST in the plugins: list. Do not place it after other plugins. This is required because the receiver clears the in_progress queue on startup and must be listening for webhooks, processing them if there is a completed item that came in while it was down, before handlers begin processing jobs.
  • IMPORTANT: On first start, it will scan for failed webhook deliveries for the past 24 hours and send a re-delivery request for each one. This is to ensure that all webhooks are delivered and processed and nothing in your plugins are orphaned or database. Avoid excessive restarts or else you'll eat up your API limits quickly. You can use skip_redeliver: true to disable this behavior.

Once configured, you can run Anklet and, if everything is configured properly, you should see logs like this:

{"time":"2025-01-06T10:38:23.198354-06:00","level":"INFO","msg":"starting plugin","ankletVersion":"0.11.2","pluginName":"GITHUB_WEBHOOK_RECEIVER"}
{"time":"2025-01-06T10:38:23.199399-06:00","level":"INFO","msg":"listing hook deliveries for the last 24 hours to see if any need redelivery (may take a while)...","ankletVersion":"0.11.2","pluginName":"GITHUB_WEBHOOK_RECEIVER","plugin":"github_receiver"}
{"time":"2025-01-06T10:38:27.186532-06:00","level":"INFO","msg":"started plugin","ankletVersion":"0.11.2","pluginName":"GITHUB_WEBHOOK_RECEIVER","plugin":"github_receiver"}

It should now be ready to receive webhooks. You can now set up a webhook to send events to this receiver.

API Endpoints

  • /jobs/v1/receiver - This is the endpoint that Github will send the webhook to. This is where the receiver will receive the webhook and store it in the database.

Webhook Trigger Setup

  1. Find your repo (or organization) in github.com
  2. Click on Settings
  3. Click on Webhooks
  4. Click on Add webhook
  5. Set the Payload URL to the Public IP or URL that points to the server running the Anklet Github Receiver + /jobs/v1/receiver. So for example: http://{PUBLIC IP OR URL}:54321/jobs/v1/receiver
  6. Set Content Type to application/json
  7. Set the Secret to the secret from the config.yml
  8. SSL verfifcation is up to you.
  9. Choose Workflow jobs as the event to trigger/receive
  10. Make sure Active is enabled
  11. Click on Add webhook

API Limits

The following logic consumes API limits. Should you run out, all processing will pause until the limits are reset after the specific github duration and then resume where it left off.

  • Requesting all hook deliveries for the past 24 hours.
  • To get verbose information for each hook delivery that's in_progress still.
  • Then again to post the redelivery request if all other conditions are met indicating it was orphaned.

Metrics

Key Names and Descriptions

Key Description
plugin_status Status of the service (idle, running, limit_paused, stopped)
plugin_status_since Time the plugin status was last updated
host_cpu_count Total CPU count of the host
host_cpu_used_count Total in use CPU count of the host
host_cpu_usage_percentage CPU usage percentage of the host
host_memory_total_bytes Total memory of the host (bytes)
host_memory_used_bytes Used memory of the host (bytes)
host_memory_available_bytes Available memory of the host (bytes)
host_memory_usage_percentage Memory usage percentage of the host
host_disk_total_bytes Total disk space of the host (bytes)
host_disk_used_bytes Used disk space of the host (bytes)
host_disk_available_bytes Available disk space of the host (bytes)
host_disk_usage_percentage Disk usage percentage of the host 
❯ curl -s http://127.0.0.1:8080/metrics/v1\?format\=prometheus
plugin_status{name=GITHUB_RECEIVER,plugin=github_receiver,owner=veertuinc} running
plugin_status_since{name=GITHUB_RECEIVER,plugin=github_receiver,owner=veertuinc} 2025-01-07T11:42:57-06:00
host_cpu_count 12
host_cpu_used_count 5
host_cpu_usage_percentage 42.171734
host_memory_total_bytes 38654705664
host_memory_used_bytes 28486483968
host_memory_available_bytes 10168221696
host_memory_usage_percentage 73.694738
host_disk_total_bytes 994662584320
host_disk_used_bytes 623034486784
host_disk_available_bytes 371628097536
host_disk_usage_percentage 62.637773


---

## Healthcheck

A Healthcheck endpoint is available at `http://{url/ip}:{port}/healthcheck`. It will return a 200 status code and `ok` if the plugin is running.

## FAQS

1. Available `plugin_status` values are: `running`, `in_progress`, `limit_paused`, `idle`, `stopped`.
  - `running`: The plugin has started and is available to run a job.
  - `in_progress`: The plugin has picked up a job to run.
  - `limit_paused`: The plugin is paused because of Github API rate limits. (will continue once the rate limits are reset after the specific github duration)
  - `idle`: The plugin is idle.
  - `stopped`: The plugin is stopped.