Merge branch 'ISD-2412-SSDLC-Cryptographic-Documentation' of github.c…

…om:canonical/github-runner-operator into ISD-2412-SSDLC-Cryptographic-Documentation

.github/pull_request_template.md

@@ -29,5 +29,6 @@ Applicable spec: <link>
 - [ ] The documentation for charmhub is updated.
 - [ ] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`).
 - [ ] The changelog is updated with changes that affects the users of the charm.
+- [ ] The changes do not introduce any regression in code or tests related to LXD runner mode.
 
 <!-- Explanation for any unchecked items above -->

.github/workflows/e2e_test_run.yaml

@@ -37,6 +37,7 @@ jobs:
     runs-on: [self-hosted, linux, "${{ inputs.runner-tag }}"]
     steps:
       - name: Hostname is set to "github-runner"
+        if: "${{ github.event.inputs.runner-virt-type == 'openstack' }}"
         run: sudo hostnamectl hostname | grep github-runner
       # Snapd can have some issues in privileged LXD containers without setting
       # security.nesting=True and this.

.github/workflows/integration_test.yaml

@@ -19,11 +19,11 @@ jobs:
       pre-run-script: scripts/pre-integration-test.sh
       provider: lxd
       test-tox-env: integration-juju3.1
-      # These important local LXD test has no OpenStack integration versions.
+      # These important local LXD test have no OpenStack integration versions.
       # test_charm_scheduled_events ensures reconcile events are fired on a schedule.
       # test_debug_ssh ensures tmate SSH actions works.
-      # TODO: Add OpenStack integration versions of these tests.
-      modules: '["test_charm_scheduled_events", "test_debug_ssh"]'
+      # The test test_charm_upgrade needs to run to ensure the charm can be upgraded.
+      modules: '["test_charm_scheduled_events", "test_debug_ssh", "test_charm_upgrade"]'
   openstack-interface-tests-private-endpoint:
     name: openstack interface test using private-endpoint
     uses: canonical/operator-workflows/.github/workflows/integration_test.yaml@main

.github/workflows/scheduled_e2e_test.yaml

@@ -7,6 +7,8 @@ on:
   schedule:
     - cron: "15 4 * * 2"
 
+  workflow_dispatch:
+
 jobs:
   build-charm:
     name: Build Charm
@@ -246,12 +248,12 @@ jobs:
           # https://docs.github.com/en/actions/using-workflows/triggering-a-workflow#triggering-a-workflow-from-a-workflow
           GH_TOKEN: ${{ matrix.event.name == 'workflow_dispatch' && secrets.GITHUB_TOKEN || secrets.E2E_TESTING_TOKEN }}
         run: |
-          # Base any future branches on the current branch
+          # Base any future branches on the current branch.
           REF_SHA=$(gh api \
             -H "Accept: application/vnd.github+json" \
             -H "X-GitHub-Api-Version: 2022-11-28" \
             /repos/${{ secrets.E2E_TESTING_REPO }}/git/ref/heads/$GITHUB_REF_NAME \
-            --jq .object.sha)
+            --jq .object.sha) || (echo "Failed to get REF_SHA using $GITHUB_REF_NAME" && false)
 
           # Create a temporary reference/branch
           # For push, this should trigger the "Push Event Tests" workflow automatically

.github/workflows/scheduled_integration_test.yaml

@@ -7,6 +7,8 @@ on:
   schedule:
     - cron: "15 5 * * 2"
 
+  workflow_dispatch:
+
 jobs:
   # test option values defined at test/conftest.py are passed on via repository secret
   # INTEGRATION_TEST_ARGS to operator-workflows automatically.
@@ -29,4 +31,4 @@ jobs:
       pre-run-script: scripts/pre-integration-test.sh
       provider: lxd
       test-tox-env: integration-juju3.1
-      modules: '["test_charm_base_image", "test_charm_fork_repo", "test_charm_no_runner", "test_charm_scheduled_events", "test_charm_lxd_runner", "test_charm_runner", "test_charm_metrics_success", "test_charm_metrics_failure", "test_self_hosted_runner", "test_charm_with_proxy", "test_charm_with_juju_storage", "test_debug_ssh", "test_charm_upgrade", "test_reactive"]'
+      modules: '["test_charm_base_image", "test_charm_fork_repo", "test_charm_no_runner", "test_charm_scheduled_events", "test_charm_lxd_runner", "test_charm_runner", "test_charm_metrics_success", "test_charm_metrics_failure", "test_self_hosted_runner", "test_charm_with_proxy", "test_charm_with_juju_storage", "test_debug_ssh", "test_charm_upgrade"]'

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contribute
+
+## Overview
+
+This document explains the processes and practices recommended for contributing enhancements to the GitHub Runner operator.
+
+* Generally, before developing enhancements to this charm, 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/).
+* Familiarizing yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library will help you a lot when working on new features or bug fixes.
+* All enhancements require review before being merged. Code review typically examines
+  * code quality
+  * test coverage
+  * user experience for Juju administrators of this charm.
+For more details, check our [contributing guide](https://github.com/canonical/is-charms-contributing-guide/blob/main/CONTRIBUTING.md).
+
+## Developing
+
+For any problems with this charm, please [report bugs here](https://github.com/canonical/github-runner-operator/issues).
+
+The code for this charm can be downloaded as follows:
+
+```shell
+git clone https://github.com/canonical/github-runner-operator.git
+```
+
+Prior to working on the charm ensure juju is connected to an LXD cloud,  see the [upstream documentation](https://juju.is/docs/lxd-cloud) for details.
+
+### Testing
+
+This project uses `tox` for managing test environments. There are some pre-configured environments
+that can be used for linting and formatting code when you're preparing contributions to the charm:
+
+* `tox`: Runs all of the basic checks (`lint`, `unit`, `static`, and `coverage-report`).
+* `tox -e fmt`: Runs formatting using `black` and `isort`.
+* `tox -e lint`: Runs a range of static code analysis to check the code.
+* `tox -e static`: Runs other checks such as `bandit` for security issues.
+* `tox -e unit`: Runs the unit tests.
+* `tox -e integration`: Runs the integration tests.
+
+> NOTE: Integration tests are currently intended to run on the CI and may not work locally without further argument.
+### Generating src docs for every commit
+
+Run the following command:
+
+```bash
+echo -e "tox -e src-docs\ngit add src-docs\n" >> .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+### Building the charm
+
+Build the charm in this git repository using:
+
+```shell
+charmcraft pack
+```
+
+## Canonical Contributor Agreement
+
+Canonical welcomes contributions to the GitHub Runner Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you’re interested in contributing to the solution.

README.md

@@ -6,7 +6,7 @@
 
 ## Description
 
-This machine charm creates [self-hosted runners for running GitHub Actions](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). Each unit of this charm will start a configurable number of LXD based containers and virtual
+This machine charm creates [self-hosted runners for running GitHub Actions](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners). Each unit of this charm will start a configurable number of OpenStack or LXD based containers and virtual
 machines to host them. Every runner performs only one job, after which it unregisters from GitHub to ensure that each job runs in
 a clean environment.
 

docs/changelog.md

@@ -1,5 +1,33 @@
 # Changelog
 
+### 2024-10-17
+
+- Use in-memory authentication instead of clouds.yaml on disk for OpenStack. This prevents
+the multi-processing fighting over the file handle for the clouds.yaml file in the github-runner-manager.
+
+- Fixed a bug where metrics storage for unmatched runners could not get cleaned up.
+
+### 2024-10-11
+
+- Added support for COS integration with reactive runners.
+- The charm now creates a dedicated user which is used for running the reactive process and 
+  storing metrics and ssh keys (also for non-reactive mode).
+
+### 2024-10-07
+
+- Fixed the removal of proxy vars in `.env` file for LXD runners.
+- Fixed a regression in the removal of leftover directories.
+- Improved reconciliation for reactive runners.
+
+### 2024-09-27
+
+- Added job label validation when consuming a job from the message queue.
+
+### 2024-09-24
+
+- Added support for spawning a runner reactively.
+- Fixed a bug where busy runners are killed instead of only idle runners.
+
 ### 2024-09-18
 
 - Changed code to be able to spawn a runner in reactive mode.

docs/how-to/contribute.md

@@ -1,32 +1,3 @@
 # How to contribute
 
-## Overview
-
-This document explains the processes and practices recommended for contributing enhancements to the GitHub Runner operator.
-
-* Generally, before developing enhancements to this charm, 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 Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev) or [Discourse](https://discourse.charmhub.io/).
-* Familiarizing yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk) library will help you a lot when working on new features or bug fixes.
-* All enhancements require review before being merged. Code review typically examines
-  * code quality
-  * test coverage
-  * user experience for Juju administrators of this charm.
-For more details, check our [contributing guide](https://github.com/canonical/is-charms-contributing-guide/blob/main/CONTRIBUTING.md).
-
-## Developing
-
-For any problems with this charm, please [report bugs here](https://github.com/canonical/github-runner-operator/issues).
-
-The code for this charm can be downloaded as follows:
-
-```shell
-git clone https://github.com/canonical/github-runner-operator.git
-```
-
-Prior to working on the charm ensure juju is connected to an LXD cloud,  see the [upstream documentation](https://juju.is/docs/lxd-cloud) for details.
-
-To test the charm, unit test can be ran with `tox -e unit` and the integration test on juju 3.1 can be ran with `tox -e integration-juju3.1`.
-
-## Canonical Contributor Agreement
-
-Canonical welcomes contributions to the GitHub Runner Operator. Please check out our [contributor agreement](https://ubuntu.com/legal/contributors) if you’re interested in contributing to the solution.
+See the [contributing guide](https://github.com/canonical/github-runner-operator/blob/main/CONTRIBUTING.md) on GitHub.

docs/index.md

@@ -1,23 +1,20 @@
-A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) for deploying and managing [GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on virtual machines.
+# GitHub Runner Operator
 
-This charm simplifies the initial deployment and "day N" operations of GitHub self-hosted runners. The charm makes it easy to manage self-hosted runners with security and hardware resource usage in mind.
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) for deploying and managing [GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on virtual machines. The charm maintains a set of ephemeral self-hosted runners, each isolated in a single-use virtual machine instance. 
 
-Operating a self-hosted runner comes with [certain security concerns according to GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security).
-Just like GitHub's, the self-hosted runners managed by the charm are isolated in a single-use virtual machine.
-
-Some of the charm dependencies upgrades on a schedule to migrate security risks. The landscape-client charm can be deployed with this charm to ensure other dependencies are up to date.
-
-The charm maintains a set of ephemeral self-hosted runners, each isolated in a single-use virtual machine instance. In addition, resource limits for the self-hosted runners can be configured.
+Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. 
+For the github-runner-operator charm, this includes:
+* Stateless operation.
+* Configurable resource limits.
+* Ability to redeploy without losing any data (no need to back up).
+* Supported observability through the `cos-agent` integration.
+* Scheduled dependences upgrades to mitigate security risks. Furthermore, the landscape-client charm can be deployed with this charm to ensure other dependencies are kept up to date.
 
-See [charm architecture](https://charmhub.io/github-runner/docs/explanation-charm-architecture) for more information.
-
-The charm operates in a stateless manner. It can be redeployed without losing any data and there is no need to backup the charm's state.
+Operating a self-hosted runner comes with [certain security concerns according to GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security).
+Just like GitHub's runners, the self-hosted runners managed by the charm are isolated in a single-use virtual machine.
 
-The charm also supports observability through the optional `cos-agent` integration.
 Metrics and logs about the runners and the charm itself are collected and sent to the [Canonical Observability Stack](https://charmhub.io/topics/canonical-observability-stack) for analysis and visualisation.
 
-This charm will make operating GitHub self-hosted runners simple and straightforward for DevOps or SRE teams through Juju's clean interface.
-
 The charm enforces a set of GitHub repository settings as best practice. This is planned to be opt-in in the future. See [How to comply with repository policies](https://charmhub.io/github-runner/docs/how-to-repo-policy).
 
 ## In this documentation
@@ -46,20 +43,24 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
 
 # Contents
 
-1. [Explanation](explanation)
-  1. [ARM64](explanation/arm64.md)
-  1. [Charm architecture](explanation/charm-architecture.md)
-1. [How To](how-to)
-  1. [How to add custom labels](how-to/add-custom-labels.md)
-  1. [How to change repository or organization](how-to/change-path.md)
-  1. [How to change GitHub personal access token](how-to/change-token.md)
-  1. [How to comply with security requirements](how-to/comply-security.md)
-  1. [How to restrict self-hosted runner network access](how-to/configure-denylist.md)
-  1. [How to contribute](how-to/contribute.md)
-  1. [How to deploy on ARM64](how-to/deploy-on-arm64.md)
-  1. [How to integrate with COS](how-to/integrate-with-cos.md)
-  1. [How to comply with repository policies](how-to/repo-policy.md)
-  1. [How to run on LXD cloud](how-to/run-on-lxd.md)
+1. [Tutorial](tutorial)
+  1. [Managing resource usage](tutorial/managing-resource-usage.md)
+  1. [Quick start](tutorial/quick-start.md)
+1. [How to](how-to)
+  1. [Add custom labels](how-to/add-custom-labels.md)
+  1. [Change repository or organization](how-to/change-path.md)
+  1. [Change GitHub personal access token](how-to/change-token.md)
+  1. [Comply with security requirements](how-to/comply-security.md)
+  1. [Restrict self-hosted runner network access](how-to/configure-denylist.md)
+  1. [Configure runner storage](how-to/configure-runner-storage.md)
+  1. [Contribute](how-to/contribute.md)
+  1. [Debug with SSH](how-to/debug-with-ssh.md)
+  1. [Deploy on ARM64](how-to/deploy-on-arm64.md)
+  1. [Integrate with COS](how-to/integrate-with-cos.md)
+  1. [Spawn OpenStack runner](how-to/openstack-runner.md)
+  1. [Comply with repository policies](how-to/repo-policy.md)
+  1. [Run on LXD cloud](how-to/run-on-lxd.md)
+  1. [Set base image](how-to/set-base-image.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [ARM64](reference/arm64.md)
@@ -68,6 +69,6 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
   1. [External Access](reference/external-access.md)
   1. [Integrations](reference/integrations.md)
   1. [Token scopes](reference/token-scopes.md)
-1. [Tutorial](tutorial)
-  1. [Managing resource usage](tutorial/managing-resource-usage.md)
-  1. [Quick start](tutorial/quick-start.md)
+1. [Explanation](explanation)
+  1. [ARM64](explanation/arm64.md)
+  1. [Charm architecture](explanation/charm-architecture.md)

docs/reference/actions.md

@@ -1,3 +1,5 @@
 # Actions
 
-See [Actions](https://charmhub.io/github-runner/actions).
+See [Actions](https://charmhub.io/github-runner/actions).
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)

docs/reference/configurations.md

@@ -1,3 +1,5 @@
 # Configurations
 
-See [Configure](https://charmhub.io/github-runner/configure).
+See [Configurations](https://charmhub.io/github-runner/configure).
+
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)

docs/reference/cos.md

@@ -13,7 +13,7 @@ The "GitHub Self-Hosted Runner Metrics" metrics dashboard presents the following
 - General: Displays general metrics about the charm and runners, such as:
   - Lifecycle counters: Tracks the frequency of Runner initialisation, start, stop, and crash events.
   - Available runners: A horizontal bar graph showing the number of runners available during the last reconciliation event. Note: This data is updated after each reconciliation event and is not real-time.
-  - Idle runners after reconciliation: A time series graph showing the number of runners marked as idle during the last reconciliation event over time. Note: This data is updated after each reconciliation event and is not real-time.
+  - Runners after reconciliation: A time series graph showing the number of runners marked as active/idle during the last reconciliation event over time. Note: This data is updated after each reconciliation event and is not real-time.
   - Duration observations: Each data point aggregates the last hour and shows the 50th, 90th, 95th percentile and maximum durations for:
       - Runner installation
       - Runner idle duration

docs/reference/integrations.md

@@ -2,10 +2,13 @@
 
 ### debug-ssh
 
-_Interface_: debug-ssh
+_Interface_: debug-ssh    
 _Supported charms_: [tmate-ssh-server](https://charmhub.io/tmate-ssh-server)
 
 Debug-ssh integration provides necessary information for runners to provide ssh reverse-proxy
 applications to setup inside the runner. 
 
-Example debug-ssh integrate command: `juju integrate github-runner tmate-ssh-server`
+Example debug-ssh integrate command: 
+```
+juju integrate github-runner tmate-ssh-server
+```