Repository: canonical/github-runner-operator
Pull request #489: Add security documentation
Author: login: yhaliaw
Labels: name: documentation
description: Improvements or additions to documentation
name: trivial
name: Libraries: Out of sync
Created: 2025-03-19T03:10:33Z | Merged: 2025-03-26T02:55:47Z

### Overview

<!-- A high level overview of the change -->

Add security related documentation.

### Rationale

<!-- The reason the change is needed -->

### Checklist

- [x] The [charm style guide](https://juju.is/docs/sdk/styleguide) was applied.
- [x] The [contributing guide](https://github.com/canonical/is-charms-contributing-guide) was applied.
- [x] The changes are compliant with [ISD054 - Managing Charm Complexity](https://discourse.charmhub.io/t/specification-isd014-managing-charm-complexity/11619)
- [x] The documentation for charmhub is updated.
- [x] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`).
- [x] The changelog is updated with changes that affects the users of the charm.

<!-- Explanation for any unchecked items above -->


Diff:
diff --git a/docs/changelog.md b/docs/changelog.md
index 7deb02b8c7..daa96931fa 100644
--- a/docs/changelog.md
+++ b/docs/changelog.md
@@ -1,5 +1,9 @@
 # Changelog
 
+### 2025-03-25
+
+- Add documentation explaining security design of the charm.
+
 ### 2025-03-24
 
 - New terraform product module. This module is composed of one github-runner-image-builder application and the related
diff --git a/docs/explanation/security.md b/docs/explanation/security.md
new file mode 100644
index 0000000000..3a39115194
--- /dev/null
+++ b/docs/explanation/security.md
@@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm manages a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners, which poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organizations or repositories.
+
+For third-party contributions, the charm can integrate with the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository so that only workflows from trusted users are able to run on the runners.
+- For outside collaborators: Use the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use a [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes) for more information.
+
+### Good practices
+
+- Use a fine-grained personal access token.
+- Give the minimal permission required.
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs run within the OpenStack servers, it is recommended to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources outside of their own OpenStack project. See [the OpenStack documentation](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprises to manage outgoing network traffic through HTTP(S) proxies. By funneling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with a HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken precautions to manage the access of the OpenStack servers hosting the runner application. An OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
+
+- Receive traffic on port 22: Needed for the charm to manage the OpenStack server.
+- Send traffic on port 10022: Needed for the integration with [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server).
+
+Other OpenStack security rules can be enforced by the OpenStack host. Enabling all port for egress is a common default OpenStack security rule. The above network traffic rules are what the charm manages.
diff --git a/docs/how-to/comply-security.md b/docs/how-to/comply-security.md
index 6ce195b832..0750ddf75c 100644
--- a/docs/how-to/comply-security.md
+++ b/docs/how-to/comply-security.md
@@ -2,9 +2,9 @@
 
 According to GitHub, running code inside the GitHub self-hosted runner [poses a significant security risk of arbitrary code execution](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security). The self-hosted runners managed by the charm are isolated in its own single-use virtual machine instance. In addition, the charm enforces some repository settings to ensure all code running on the self-hosted runners is reviewed by someone trusted.
 
-The repository settings are enforced with the [repo-policy-compliance Python library](https://github.com/canonical/repo-policy-compliance). The enforced rules differ depending on how the GitHub Actions workflow is triggered. The details can be found in the [README](https://github.com/canonical/repo-policy-compliance/blob/main/README.md).
+The charm can be integrated with the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to enforce a set of good practices around GitHub repository settings. Self-hosted runners managed by the charm will not run jobs on repositories unless they are compliant with the practices.
 
-In this guide, a recommended set of policies will be presented, but any set repository settings that passes the [Python library](https://github.com/canonical/repo-policy-compliance) checks will work with the self-hosted runners managed by this charm.
+In this guide, a recommended set of policies will be presented.
 
 ## Recommended policy
 
diff --git a/docs/how-to/openstack-runner.md b/docs/how-to/openstack-runner.md
index 7201309f8b..20f56b18e3 100644
--- a/docs/how-to/openstack-runner.md
+++ b/docs/how-to/openstack-runner.md
@@ -58,5 +58,5 @@ Note that the network should be configured to allow traffic from the charm deplo
 
 The network documentation is [here](https://docs.openstack.org/neutron/latest/admin/intro-os-networking.html).
 
-> NOTE: The name of the application must not be longer than 50 characters. A valid runner name is 64 characters or less in length and does not include '"', '/', ':',
-'<', '>', '\', '|', '*' and '?'. 14 characters are reserved for Juju unit number and unique identifier.
\ No newline at end of file
+> NOTE: The name of the application must not be longer than 48 characters. A valid runner name is 64 characters or less in length and does not include '"', '/', ':',
+'<', '>', '\', '|', '*' and '?'. 16 characters are reserved for Juju unit number, unique identifier and other information.
diff --git a/docs/how-to/repo-policy.md b/docs/how-to/repo-policy.md
deleted file mode 100644
index 242b14861e..0000000000
--- a/docs/how-to/repo-policy.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# How to comply with repository policies
-
-The charm enforces a set of best practice GitHub repository settings. Self-hosted runners managed by the charm will not run jobs on repositories not compliant with the practices. This will be opt-in in the future.
-
-The repository settings are enforced with this [Python library](https://github.com/canonical/repo-policy-compliance). The rules enforced are different depending on how the GitHub Actions workflow is triggered. The details can be found in the README.
-
-In this guide, a recommended set of policies will be presented, but any set repository settings that passes the [Python library](https://github.com/canonical/repo-policy-compliance) checks will work with the self-hosted runners managed by this charm.
-
-## Recommended policy
-
-- For outside collaborators the permission should be set to read. See [here](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/managing-teams-and-people-with-access-to-your-repository#changing-permissions-for-a-team-or-person) for instructions to change collaborator permissions. Outside collaborators will still be able to contribute with pull requests, but reviews will be needed. Details in a later section.
-- Create the following branch protection rules, with the instructions [here](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule):
-  - branch name pattern matching only the default branch of the repository, such as `main`, with the follow enabled:
-    - `Dismiss stale pull request approvals when new commits are pushed`
-    - `Do not allow bypassing the above settings`
-
-With these settings, the common workflow of creating branches with pull requests and merging to the default branch is supported. Other GitHub Actions workflow triggers such as workflow_dispatch, push, and schedule are supported as well.
-
-### Working with outside collaborators
-
-Contributions from outside collaborators (in the case where a repository is public) need to be handled slightly differently. As such, this charm requires pull requests by outside collaborators to be reviewed by someone with `write` permission or above. Once the review is completed, the reviewer should add a comment including the following string: `/canonical/self-hosted-runners/run-workflows <commit SHA>`, where `<commit SHA>` is the commit SHA of the approved commit. Once posted, the self-hosted runners will run the workflow for this commit.
\ No newline at end of file
diff --git a/docs/index.md b/docs/index.md
index b84af7ea55..d3e63b89c3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -15,7 +15,7 @@ Just like GitHub's runners, the self-hosted runners managed by the charm are iso
 
 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.
 
-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).
+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 security requirements](https://charmhub.io/github-runner/docs/how-to-comply-security).
 
 ## In this documentation
 
@@ -54,7 +54,6 @@ Thinking about using the GitHub runner charm for your next project? [Get in touc
   1. [Debug with SSH](how-to/debug-with-ssh.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. [Set up reactive spawning](how-to/reactive.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)


Reviews:
user: login: erinecon
body: Thanks for adding security documentation! 
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-19T12:44:03Z
user: login: javierdelapuente
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-19T14:08:47Z
user: login: yhaliaw
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-20T02:20:39Z
user: login: yhaliaw
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-20T02:24:03Z
user: login: yhaliaw
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-03-20T02:24:21Z
user: login: javierdelapuente
state: APPROVED
author_association: COLLABORATOR
submitted_at: 2025-03-20T06:40:24Z
user: login: erinecon
body: Looks great -- two more minor comments from me!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T11:52:47Z
user: login: erinecon
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T11:53:01Z

Review comments:
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
path: docs/explanation/security.md
user: login: javierdelapuente
body: ```suggestion
This document describes the security design of the GitHub runner charm. The charm manages a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
```
created_at: 2025-03-19T07:39:04Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
This document describes the security design of the GitHub runner charm. The charm manages a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
```
created_at: 2025-03-19T12:25:38Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners, which poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organizations or repositories.
```
created_at: 2025-03-19T12:26:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
For third-party contributions, the charm can integrate with the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
```
created_at: 2025-03-19T12:28:22Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- Only register the GitHub self-hosted runners to a trusted organization or repository so that only workflows from trusted users are able to run on the runners.
```
created_at: 2025-03-19T12:29:12Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- For outside collaborators: Use the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
```
created_at: 2025-03-19T12:29:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
It is generally recommended to grant the minimal permissions necessary for security reasons. Use a [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes) for more information.
```
created_at: 2025-03-19T12:30:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- Use a fine-grained personal access token.
```
created_at: 2025-03-19T12:30:51Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- Give the minimal permission required.
```
Nitpick: Since you already linked this reference document above, I don't think you need to link it again :)
created_at: 2025-03-19T12:31:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommended to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources outside of their own OpenStack project. See [the OpenStack documentation](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
```
created_at: 2025-03-19T12:33:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
It is common for enterprises to manage outgoing network traffic through HTTP(S) proxies. By funneling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
```
created_at: 2025-03-19T12:36:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
```
It seems like a repeated sentence to me -- let me know if I misunderstood
created_at: 2025-03-19T12:36:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- Use aproxy to make GitHub Actions work transparently with a HTTP(S) proxy.
```
created_at: 2025-03-19T12:37:16Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken pre-caution to manage the access of the OpenStack servers hosting the runner application. OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken precautions to manage the access of the OpenStack servers hosting the runner application. An OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
```
created_at: 2025-03-19T12:38:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken pre-caution to manage the access of the OpenStack servers hosting the runner application. OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
+
+- Receive traffic on port 22. Needed for the charm to manage the OpenStack server.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- Receive traffic on port 22: Needed for the charm to manage the OpenStack server.
```
Nitpick
created_at: 2025-03-19T12:39:05Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken pre-caution to manage the access of the OpenStack servers hosting the runner application. OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
+
+- Receive traffic on port 22. Needed for the charm to manage the OpenStack server.
+- Send traffic on port 10022. Needed for the integration with [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server)
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
- Send traffic on port 10022: Needed for the integration with [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server).
```
The colon is a nitpick, but please put a period at the end of the item for consistency :)
created_at: 2025-03-19T12:39:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken pre-caution to manage the access of the OpenStack servers hosting the runner application. OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
+
+- Receive traffic on port 22. Needed for the charm to manage the OpenStack server.
+- Send traffic on port 10022. Needed for the integration with [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server)
+
+Other OpenStack security rules can be enforced by the OpenStack host. Enabling all port for egress is a common default OpenStack security rule. The above is what the charm manages.
path: docs/explanation/security.md
user: login: erinecon
body: What does "the above" refer to -- the ports, the traffic, or something else? It would be good to clarify 
created_at: 2025-03-19T12:40:13Z
author_association: CONTRIBUTOR
diff_hunk: @@ -2,9 +2,9 @@
 
 According to GitHub, running code inside the GitHub self-hosted runner [poses a significant security risk of arbitrary code execution](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security). The self-hosted runners managed by the charm are isolated in its own single-use virtual machine instance. In addition, the charm enforces some repository settings to ensure all code running on the self-hosted runners is reviewed by someone trusted.
 
-The repository settings are enforced with the [repo-policy-compliance Python library](https://github.com/canonical/repo-policy-compliance). The enforced rules differ depending on how the GitHub Actions workflow is triggered. The details can be found in the [README](https://github.com/canonical/repo-policy-compliance/blob/main/README.md).
+The charm can be integrated with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to enforce a set of good practice GitHub repository settings. Self-hosted runners managed by the charm will not run jobs on repositories not compliant with the practices.
path: docs/how-to/comply-security.md
user: login: erinecon
body: ```suggestion
The charm can be integrated with the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to enforce a set of good practices around GitHub repository settings. Self-hosted runners managed by the charm will not run jobs on repositories unless they are compliant with the practices.
```
created_at: 2025-03-19T12:43:31Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
path: docs/explanation/security.md
user: login: yhaliaw
body: Yeah, I just thought it might be good to stress that point again.
I will remove it.
created_at: 2025-03-20T02:20:39Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
path: docs/explanation/security.md
user: login: yhaliaw
body: Updated.
created_at: 2025-03-20T02:24:03Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken pre-caution to manage the access of the OpenStack servers hosting the runner application. OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
+
+- Receive traffic on port 22. Needed for the charm to manage the OpenStack server.
+- Send traffic on port 10022. Needed for the integration with [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server)
+
+Other OpenStack security rules can be enforced by the OpenStack host. Enabling all port for egress is a common default OpenStack security rule. The above is what the charm manages.
path: docs/explanation/security.md
user: login: yhaliaw
body: Changed to "The above network traffic rules are what the charm manages.".
created_at: 2025-03-20T02:24:21Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm manages a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners, which poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organizations or repositories.
+
+For third-party contributions, the charm can integrate with the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository so that only workflows from trusted users are able to run on the runners.
+- For outside collaborators: Use the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use a [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes) for more information.
+
+### Good practices
+
+- Use a fine-grained personal access token.
+- Give the minimal permission required.
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommended to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources outside of their own OpenStack project. See [the OpenStack documentation](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs run within the OpenStack servers, it is recommended to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources outside of their own OpenStack project. See [the OpenStack documentation](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
```
created_at: 2025-03-20T11:48:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm manages a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners, which poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organizations or repositories.
+
+For third-party contributions, the charm can integrate with the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository so that only workflows from trusted users are able to run on the runners.
+- For outside collaborators: Use the [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use a [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes) for more information.
+
+### Good practices
+
+- Use a fine-grained personal access token.
+- Give the minimal permission required.
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommended to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources outside of their own OpenStack project. See [the OpenStack documentation](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprises to manage outgoing network traffic through HTTP(S) proxies. By funneling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
path: docs/explanation/security.md
user: login: erinecon
body: ```suggestion
It is common for enterprises to manage outgoing network traffic through HTTP(S) proxies. By funneling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
```
Not sure what you meant by "adopt", perhaps you meant "adapt"? In any event, I would drop it to make the sentence more concise :)
created_at: 2025-03-20T11:50:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,53 @@
+# Security in GitHub runner charm
+
+This document describes the security design of the GitHub runner charm. The charm managed a set of GitHub self-hosted runners. The GitHub self-hosted runners allow CI/CD jobs on GitHub to run on virtual machines managed by the charm. The charm supports various features with security implications.
+
+## Remote code execution risk
+
+The charm manages GitHub self-hosted runners to run GitHub Actions jobs. This allows users on GitHub to execute code on the servers hosting the runners. This poses a remote code execution risk if the code is not trusted. Therefore, the charm should only spawn runners to trusted organization or trusted repository.
+
+For third-party contribution, the charm can integrate with [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to manage the repository policy. With this integration, the self-hosted runner will not execute the GitHub jobs if the policy is not met. See [working with outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) for the recommended settings to ensure the code is reviewed by a trusted user prior to execution in the runner.
+
+### Good practices
+
+- Only register the GitHub self-hosted runners to a trusted organization or repository. So that only workflow from trusted users are able to run on the runners.
+- For outside collaborators Use [Repo Policy Compliance charm](https://charmhub.io/repo-policy-compliance) to with [policy for outside collaborators](https://charmhub.io/github-runner/docs/how-to-comply-security#working-with-outside-collaborators) to ensure the code executed in runners are reviewed by a trusted user.
+
+## Permission for GitHub app or personal access token
+
+The charm interacts with GitHub via RESTful API. This requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+It is generally recommended to grant the minimal permissions necessary for security reasons. Use [fine-grained token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) to control the scope of permission. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+### Good practices
+
+- Use fine-grained personal access token.
+- Give the minimal permission required. See [token scopes](https://charmhub.io/github-runner/docs/reference-token-scopes).
+
+## OpenStack project management
+
+The charm spawns [OpenStack servers](https://docs.openstack.org/python-openstackclient/train/cli/command-objects/server.html) to host the [GitHub self-hosted runner application](https://github.com/actions/runner). Since the GitHub jobs runs within the OpenStack servers, it is recommanded to isolate these OpenStack servers in its own [OpenStack project](https://docs.openstack.org/python-openstackclient/pike/cli/command-objects/project.html). This prevents GitHub jobs from accessing other resources by isolating them in their own OpenStack project See [here](https://docs.openstack.org/keystone/pike/admin/cli-manage-projects-users-and-roles.html) on how to manage OpenStack projects and users. See [spawning OpenStack runner](https://charmhub.io/github-runner/docs/how-to-openstack-runner) for how to make the charm utilize the OpenStack user and project.
+
+### Good practices
+
+- Have a separate OpenStack user and OpenStack project for the self-hosted runner to use.
+
+## Proxied environment
+
+It is common for enterprise or to manage outgoing network traffic through HTTP(S) proxies. By funnelling all outgoing traffic through a proxy, there is a single point to control and observe the network traffic for administrators. If the OpenStack server hosting the runners is in such an environment, the GitHub workflow would have to adopt to route all traffic through the HTTP(S) proxies. Many popular GitHub Actions were designed to be ran on the GitHub provided runners which is not in a proxied environment. Hence many GitHub Actions do not work with HTTP(S) proxies.
+
+To address this issue, the charm utilizes [aproxy](https://github.com/canonical/aproxy), a service that routes outgoing network traffic to a configured endpoint. The charm uses aproxy to transparently route outgoing traffic through the configured HTTP(S) proxy, ensuring that GitHub Actions work out of the box in a proxied environment. GitHub actions should work out of the box in a proxied environment with this. Aproxy can be enabled via [a charm configuration](https://charmhub.io/github-runner/configurations#experimental-use-aproxy).
+
+### Good practices
+
+- Manage the outgoing network traffic with a HTTP(S) proxy.
+- Use aproxy to make GitHub Actions work transparently with HTTP(S) proxy.
+
+## OpenStack server network traffic
+
+The charm spawns OpenStack servers to host the GitHub self-hosted runner application. The charm has taken pre-caution to manage the access of the OpenStack servers hosting the runner application. OpenStack security group is used to manage the egress and ingress traffic. The OpenStack server is able to:
+
+- Receive traffic on port 22. Needed for the charm to manage the OpenStack server.
+- Send traffic on port 10022. Needed for the integration with [tmate-ssh-server charm](https://charmhub.io/tmate-ssh-server)
+
+Other OpenStack security rules can be enforced by the OpenStack host. Enabling all port for egress is a common default OpenStack security rule. The above is what the charm manages.
path: docs/explanation/security.md
user: login: erinecon
body: Thanks for clarifying! 
created_at: 2025-03-20T11:53:01Z
author_association: CONTRIBUTOR

PR comments:
user: login: github-actions[bot]
created_at: 2025-03-25T12:14:15Z
body: ## Test results for commit 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

Test coverage for 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

  ```
Wrote XML report to coverage/coverage.xml
```
  Static code analysis report

  ```
Run started:2025-03-25 11:30:24.080460

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 1640
	Total lines skipped (#nosec): 2
	Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 2

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
```
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-03-25T14:42:51Z
body: ## Test results for commit 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

Test coverage for 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

  ```
Wrote XML report to coverage/coverage.xml
```
  Static code analysis report

  ```
Run started:2025-03-25 11:30:24.080460

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 1640
	Total lines skipped (#nosec): 2
	Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 2

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
```
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-03-25T14:54:14Z
body: ## Test results for commit 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

Test coverage for 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

  ```
Wrote XML report to coverage/coverage.xml
```
  Static code analysis report

  ```
Run started:2025-03-25 11:30:24.080460

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 1640
	Total lines skipped (#nosec): 2
	Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 2

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
```
author_association: CONTRIBUTOR
user: login: github-actions[bot]
created_at: 2025-03-25T15:04:29Z
body: ## Test results for commit 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

Test coverage for 04564cb8e0c44d0c6a19926bcb4bb9609d2d1e17

  ```
Wrote XML report to coverage/coverage.xml
```
  Static code analysis report

  ```
Run started:2025-03-25 11:30:24.080460

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 1640
	Total lines skipped (#nosec): 2
	Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 2

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
```
author_association: CONTRIBUTOR