feat: bootstrap with initial webhook receiver logic

.github/.jira_sync_config.yaml

@@ -0,0 +1,16 @@
+# See https://github.com/canonical/gh-jira-sync-bot for config
+settings:
+  jira_project_key: "ISD"
+
+  status_mapping:
+    opened: Untriaged
+    closed: done
+    not_planned: rejected
+
+  add_gh_comment: true
+
+  epic_key: ISD-3981
+
+  label_mapping:
+    bug: Bug
+    enhancement: Story

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+### Overview
+
+<!-- A high level overview of the change -->
+
+### Rationale
+
+<!-- The reason the change is needed -->
+
+### Checklist
+
+- [ ] The PR is tagged with appropriate label (`urgent`, `trivial`, `senior-review-required`, `documentation`).
+
+<!-- Explanation for any unchecked items above -->

.github/workflows/tests.yaml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  pull_request:
+  workflow_call:
+
+concurrency:
+  group:  ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Run Unit and Lint Tests
+    runs-on: [self-hosted-linux-amd64-noble-edge]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: 1.24
+
+      - name: Ensure No Formatting Changes
+        run: |
+          go fmt ./...
+          git diff --exit-code
+
+      - name: Build and Test
+        run: |
+          go test -v -cover -race ./...

.github/workflows/webhook_gateway_tests.yaml

@@ -0,0 +1,38 @@
+name: Webhook Gateway Integration Tests
+on:
+    pull_request:
+        paths:
+          - 'webhook-gateway/**'
+          - 'internal/**'
+    workflow_call:
+
+concurrency:
+  group:  ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+
+jobs:
+  integration-test:
+    runs-on: [self-hosted-linux-amd64-noble-edge]
+    name: Run Integration Tests
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version: 1.24
+      - name: Setup rabbitmq in an OCI container
+        run: |
+          docker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management
+          until curl -fs http://localhost:15672;
+            do echo "waiting for rabbit mq"
+            sleep 2
+          done
+      - name: Run integration test
+        env:
+          RABBITMQ_CONNECT_STRING: amqp://guest:guest@localhost:5672/
+          APP_PORT: 8080
+          WEBHOOK_SECRET: fake-secret
+        run: |
+            go test -cover -v  ./webhook-gateway -integration

CODEOWNERS

@@ -0,0 +1 @@
+*       @cbartz @yhaliaw @javierdelapuente @yanksyoon @weiiwang01 @florentianayuwono

CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contribute
+
+## Overview
+
+This document explains the processes and practices recommended for contributing enhancements to the codebase.
+
+* Generally, before developing enhancements to this code base, you should consider [opening an issue](https://github.com/canonical/github-runner-operator/issues) explaining your use case.
+* If you would like to chat with us about your use-cases or proposed implementation, you can reach us at [Canonical Charm Development Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) or [Discourse](https://discourse.charmhub.io/).
+* All enhancements require review before being merged. Code review typically examines
+    * code quality
+    * test coverage
+
+## Code of conduct
+
+When contributing, you must abide by the
+[Ubuntu Code of Conduct](https://ubuntu.com/community/ethos/code-of-conduct).
+
+## Submissions
+
+If you want to address an issue or a bug in this project,
+notify in advance the people involved to avoid confusion;
+also, reference the issue or bug number when you submit the changes.
+
+- [Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/about-forks)
+  our [GitHub repository](https://github.com/canonical/github-runner-operators)
+  and add the changes to your fork, properly structuring your commits,
+  providing detailed commit messages and signing your commits.
+- Make sure the updated project builds and runs without warnings or errors;
+  this includes linting, documentation, code and tests.
+- Submit the changes as a
+  [pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork).
+
+Your changes will be reviewed in due time; if approved, they will be eventually merged.
+
+### Describing pull requests
+
+To be properly considered, reviewed and merged,
+your pull request must provide the following details:
+
+- **Title**: Summarize the change in a short, descriptive title.
+
+- **Overview**: Describe the problem that your pull request solves.
+  Mention any new features, bug fixes or refactoring.
+
+- **Rationale**: Explain why the change is needed.
+
+
+- **Checklist**: Complete the following items:
+
+    - The PR is tagged with appropriate label (`urgent`, `trivial`, `senior-review-required`, `documentation`).
+
+### Signing commits
+
+To improve contribution tracking,
+we use the [Canonical contributor license agreement](https://assets.ubuntu.com/v1/ff2478d1-Canonical-HA-CLA-ANY-I_v1.2.pdf)
+(CLA) as a legal sign-off, and we require all commits to have verified signatures.
+
+### Canonical contributor agreement
+
+Canonical welcomes contributions to this repository. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you’re interested in contributing to the solution.
+
+#### Verified signatures on commits
+
+All commits in a pull request must have cryptographic (verified) signatures.
+To add signatures on your commits, follow the
+[GitHub documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
+
+
+## Develop
+
+For any problems with this charm, please [report bugs here](https://github.com/canonical/github-runner-operator/issues).
+
+The code can be downloaded as follows:
+
+```shell
+git clone https://github.com/canonical/github-runner-operators.git
+```
+
+The code structure is as follows
+
+- `internal/`: Internal libraries for the applications
+- `webhook-gateway`: The webhook gateway application code
+
+
+### Test
+
+This project uses standard Go testing tools for unit tests and integration tests.
+You can have a look at the GitHub actions workflows in `.github/workflows/` to see how the tests are run in CI.
+
+Run unit tests using:
+
+```shell
+go test -race -v ./...
+```
+
+Run `webhook-gateway` integration tests using:
+
+```shell
+APP_PORT=8080 WEBHOOK_SECRET=fake RABBITMQ_CONNECT_STRING="amqp://guest:guest@localhost:5672/" go test -cover -v  ./webhook-gateway -integration
+```
+
+It assumes you have access to a RabbitMQ server running reachable at $RABBITMQ_CONNECT_STRING.
+You can use `docker` to run a RabbitMQ server locally:
+
+```shell
+docker run -d  --rm --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:4-management
+```
+

README.md

@@ -0,0 +1,9 @@
+# GitHub runner operators
+
+
+![WIP](https://img.shields.io/badge/status-WIP-yellow)
+
+A monorepo containing charms to operate Self-Hosted GitHub Action Runners.
+
+At the moment, it contains initial code for the `webhook-gateway`
+application, that receives and forwards GitHub webhooks to an AMQP queue.

go.mod

@@ -0,0 +1,14 @@
+module github.com/canonical/mayfly
+
+go 1.24.6
+
+require (
+	github.com/rabbitmq/amqp091-go v1.10.0
+	github.com/stretchr/testify v1.11.1
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)

go.sum

@@ -0,0 +1,14 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/rabbitmq/amqp091-go v1.10.0 h1:STpn5XsHlHGcecLmMFCtg7mqq0RnD+zFr4uzukfVhBw=
+github.com/rabbitmq/amqp091-go v1.10.0/go.mod h1:Hy4jKW5kQART1u+JkDTF9YYOQUHXqMuhrgxOEeS7G4o=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

internal/queue/producer.go

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2025 Canonical Ltd.
+ * See LICENSE file for licensing details.
+ */
+
+package queue
+
+import (
+	"context"
+	"fmt"
+
+	amqp "github.com/rabbitmq/amqp091-go"
+)
+
+func (p *AmqpProducer) Push(ctx context.Context, headers map[string]interface{}, msg []byte) error {
+	p.mu.Lock() // Lock to prevent concurrent access to connection/channel object
+	err := p.resetConnectionOrChannelIfNecessary()
+	if err != nil {
+		p.mu.Unlock()
+		return err
+	}
+
+	msgConfirmation, err := p.publishMsg(msg, headers)
+	if err != nil {
+		p.mu.Unlock()
+		return err
+	}
+	p.mu.Unlock() // Unlock to not unblock other Push calls while waiting for confirmation
+	err = waitForMsgConfirmation(ctx, msgConfirmation)
+
+	return err
+}
+
+func (p *AmqpProducer) resetConnectionOrChannelIfNecessary() error {
+	if p.amqpConnection == nil || p.amqpConnection.IsClosed() {
+		err := p.resetConnection()
+		if err != nil {
+			return err
+		}
+	}
+
+	if p.amqpChannel == nil || p.amqpChannel.IsClosed() {
+		err := p.resetChannel()
+		if err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func waitForMsgConfirmation(ctx context.Context, confirmation confirmation) error {
+	select {
+	case <-ctx.Done():
+		return ctx.Err()
+
+	case <-confirmation.Done():
+		if !confirmation.Acked() {
+			return fmt.Errorf("confirmation not acknowledged")
+		}
+	}
+	return nil
+}
+
+func (p *AmqpProducer) publishMsg(msg []byte, headers map[string]interface{}) (confirmation, error) {
+	confirmation, err := p.amqpChannel.PublishWithDeferredConfirm(
+		"",          // exchange
+		p.queueName, // routing key
+		false,       // mandatory
+		false,       // immediate
+		amqp.Publishing{
+			ContentType: "application/json",
+			Body:        msg,
+			Headers:     headers,
+		},
+	)
+
+	if err != nil {
+		return nil, fmt.Errorf("failed to publish message: %w", err)
+	}
+	return confirmation, nil
+}
+
+func (p *AmqpProducer) resetConnection() error {
+	conn, err := p.connectFunc(p.uri)
+
+	if err != nil {
+		return fmt.Errorf("failed to connect to AMQP server: %w", err)
+	}
+	p.amqpConnection = conn
+	return nil
+}
+
+func (p *AmqpProducer) resetChannel() error {
+	c, err := p.amqpConnection.Channel()
+
+	if err != nil {
+		return fmt.Errorf("failed to open channel: %w", err)
+	}
+	p.amqpChannel = c
+
+	err = c.Confirm(false)
+	if err != nil {
+		return fmt.Errorf("failed to put channel in confirm mode: %w", err)
+	}
+
+	_, err = c.QueueDeclare(
+		p.queueName, // queueName
+		true,        // durable
+		false,       // delete when unused
+		false,       // exclusive
+		false,       // no-wait
+		nil,         // arguments
+	)
+	if err != nil {
+		return fmt.Errorf("failed to declare queue: %w", err)
+	}
+	return nil
+}
+
+func NewAmqpProducer(uri string, queueName string) *AmqpProducer {
+	return &AmqpProducer{
+		uri:         uri,
+		queueName:   queueName,
+		connectFunc: amqpConnect,
+	}
+}
+
+func amqpConnect(uri string) (amqpConnection, error) {
+	amqpConnection, err := amqp.Dial(uri)
+	return &amqpConnectionWrapper{Connection: amqpConnection}, err
+}