[discourse-gatekeeper] Migrate charm docs

docs/how-to/openstack-runner.md

@@ -59,4 +59,4 @@ 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 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.
+'<', '>', '\', '|', '*' and '?'. 16 characters are reserved for Juju unit number, unique identifier and other information.

docs/how-to/repo-policy.md

@@ -0,0 +1,21 @@
+# 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.

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 security requirements](https://charmhub.io/github-runner/docs/how-to-comply-security).
+The charm enforces a set of GitHub repository settings as best practice. This is planned to be opt-in in the future. See [How to comply with repository policies](https://charmhub.io/github-runner/docs/how-to-repo-policy).
 
 ## In this documentation
 
@@ -54,6 +54,7 @@ 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)