---
title: Charmhub | Deploy GitHub runner using Charmhub - The Open Operator Collection
description: Deploy the latest version of GitHub runner on any cloud.
url: https://charmhub.io/github-runner/docs/local-lxd-how-to-integrate-with-cos
---

# GitHub runner

[Canonical IS DevOps](https://charmhub.io/publisher/canonical-is-devops "View all packages from Canonical IS DevOps")

* [Canonical IS DevOps](https://charmhub.io/publisher/canonical-is-devops "View all packages from Canonical IS DevOps")

Platform:

24.04

22.04

20.04

stable 24801f1f

```
juju deploy github-runner
```

[Learn to deploy on juju >](https://juju.is/docs/juju/manage-applications)

---

#### Contacts

##### Maintainers

+ [Launchpad Team](https://launchpad.net/~canonical-is-devops)

* [Submit a bug](https://github.com/canonical/github-runner-operator/issues)

---

Share your thoughts on this charm with the community on discourse.

[Join the discussion](https://discourse.charmhub.io/)

# How to integrate with COS

This guide demonstrates the process of integrating with the [Canonical Observability Stack (COS)](https://charmhub.io/topics/canonical-observability-stack) using the optional `cos-agent` integration provided by this charm.

The `cos-agent` integration can be consumed by the [grafana-agent](https://charmhub.io/grafana-agent) charm, which is responsible for transmitting logs, Prometheus metrics, and Grafana dashboards to the COS stack.

> NOTE: The GitHub Runner charm and `grafana-agent` charm function as machine charms, while the COS stack contains Kubernetes charms. Therefore, establishing [cross-model integrations](https://documentation.ubuntu.com/juju/3.6/reference/relation/#cross-model-relation) is necessary, along with potential firewall rule configurations to allow inter-model traffic.

## [Requirements](https://charmhub.io/github-runner/docs/local-lxd-how-to-integrate-with-cos#p-36743-requirements)

1. Deploy the GitHub Runner Charm with the application name `github-runner` in the `machine-model`.
2. Deploy the COS stack on a Kubernetes cloud (refer to [this tutorial](https://charmhub.io/topics/canonical-observability-stack/tutorials/install-microk8s)).
   * Ensure `loki`, `prometheus`, `grafana`, and `traefik` charms are deployed within a model named `k8s-model`.
   * Integration between `loki` and `traefik` is required to enable `grafana-agent` to transmit logs by setting a public IP for the Loki service accessible from the machine cloud.
   * Confirm that both models exist in the same Juju controller. If not, adjust the model names by appending the respective controller name (followed by “:”) in the subsequent steps. Ensure you have the necessary [permissions](https://documentation.ubuntu.com/juju/3.6/howto/manage-offers/#control-access-to-an-offer) to consume the offers.

## [Steps](https://charmhub.io/github-runner/docs/local-lxd-how-to-integrate-with-cos#p-36743-steps)

1. Deploy the `grafana-agent` charm in the machine model.

   ```
   juju switch machine-model
   juju deploy grafana-agent --channel latest/edge
   ```
2. Integrate the `grafana-agent` charm with the GitHub Runner charm.

   ```
   juju integrate github-runner grafana-agent
   ```
3. Create offers for `loki`, `prometheus`, and `grafana-agent` in the `k8s-model`.

   ```
   juju switch k8s-model
   juju offer loki:logging
   juju offer prometheus:receive-remote-write
   juju offer grafana:grafana-dashboard
   ```
4. Consume the offers in the machine model.

   ```
   juju switch machine-model
   juju consume loki
   juju consume prometheus
   juju consume grafana
   ```
5. Integrate the `grafana-agent` charm with `loki`, `prometheus`, and `grafana`.

   ```
   juju integrate loki-k8s grafana-agent
   juju integrate prometheus-k8s grafana-agent
   juju integrate grafana-k8s grafana-agent
   ```

You should now be able to access a Grafana Dashboard named `GitHub Self-Hosted Runner Metrics`, displaying metrics, and another named `System Resources` exhibiting host resources in Grafana.
Additionally, you can explore Loki logs using Grafana’s Explore function. For detailed information about the specific metrics in the `GitHub Self-Hosted Runner Metrics` dashboard, refer to [Metrics](https://charmhub.io/github-runner/docs/reference-cos).

---