You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
- Revert `copytruncate logrotate` method for reactive processes, as `copytruncate` keeps log files on disks and does not remove them, and each process is writing to a new file leading to a huge and increasing amount
130
-
of zero sized files in the reactive log directory. This is a temporary fix until a better solution is implemented, as it has the downside that long lived reactive processes may write to deleted log files.
131
-
133
+
of zero sized files in the reactive log directory. This is a temporary fix until a better solution is implemented, as it has the downside that long lived reactive processes may write to deleted log files.
132
134
133
135
### 2025-06-12
134
136
@@ -140,9 +142,9 @@ of zero sized files in the reactive log directory. This is a temporary fix until
140
142
141
143
### 2025-06-04
142
144
143
-
- Reduce the reconcile-interval configuration from 10 minutes to 5 minutes. This is the interval
144
-
between reconciling the current and intended number of runners. The value should be kept low,
145
-
unless GitHub API rate limiting is encountered.
145
+
- Reduce the reconcile-interval configuration from 10 minutes to 5 minutes. This is the interval
146
+
between reconciling the current and intended number of runners. The value should be kept low,
147
+
unless GitHub API rate limiting is encountered.
146
148
- Removed the reconcile-runners Juju action.
147
149
148
150
### 2025-06-03
@@ -151,9 +153,8 @@ unless GitHub API rate limiting is encountered.
151
153
152
154
### 2025-05-22
153
155
154
-
- Add possibility to run a script in the pre-job phase of a runner. This can be useful to setup
155
-
network/infrastructure specific things.
156
-
156
+
- Add possibility to run a script in the pre-job phase of a runner. This can be useful to setup
157
+
network/infrastructure specific things.
157
158
158
159
### 2025-05-09
159
160
@@ -162,8 +163,8 @@ network/infrastructure specific things.
162
163
### 2025-05-06
163
164
164
165
- The ssh health checks are removed and GitHub is used instead to get the runners health
165
-
information. This implies many changes in both the structure of the project and its functionality. Potentially, many race conditions should
166
-
disappear.
166
+
information. This implies many changes in both the structure of the project and its functionality. Potentially, many race conditions should
167
+
disappear.
167
168
168
169
### 2025-04-28
169
170
@@ -197,7 +198,7 @@ disappear.
197
198
### 2025-03-24
198
199
199
200
- New terraform product module. This module is composed of one github-runner-image-builder application and the related
200
-
github-runner applications.
201
+
github-runner applications.
201
202
202
203
### 2024-12-13
203
204
@@ -243,14 +244,14 @@ github-runner applications.
243
244
### 2024-10-17
244
245
245
246
- Use in-memory authentication instead of clouds.yaml on disk for OpenStack. This prevents
246
-
the multi-processing fighting over the file handle for the clouds.yaml file in the `github-runner-manager`.
247
+
the multi-processing fighting over the file handle for the clouds.yaml file in the `github-runner-manager`.
247
248
248
249
- Fixed a bug where metrics storage for unmatched runners could not get cleaned up.
249
250
250
251
### 2024-10-11
251
252
252
253
- Added support for COS integration with reactive runners.
253
-
- The charm now creates a dedicated user which is used for running the reactive process and
254
+
- The charm now creates a dedicated user which is used for running the reactive process and
254
255
storing metrics and ssh keys (also for non-reactive mode).
Copy file name to clipboardExpand all lines: docs/explanation/security.md
+35-3Lines changed: 35 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,14 +4,46 @@ This document describes the security design of the GitHub runner charm. The char
4
4
5
5
## Remote code execution risk
6
6
7
-
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.
7
+
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 has not been reviewed or authorized. Therefore, the charm should only spawn runners to trusted organizations or repositories.
8
8
9
-
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.
9
+
For external contributor security, see [How to manage external contributors securely](../how-to/manage-external-contributors.md) for configuration options and recommended practices.
10
10
11
11
### Good practices
12
12
13
13
- 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.
14
-
- 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.
14
+
- For outside collaborators: Use the `allow-external-contributor` configuration option (set to `false`) to restrict workflow execution to users with COLLABORATOR, MEMBER, or OWNER status. This prevents unauthorized code execution from external contributors.
15
+
- Configure appropriate repository settings and protection rules to ensure the code executed in runners are reviewed by a trusted user.
16
+
17
+
### Recommended security practices
18
+
19
+
When working with external contributors, consider the following security practices:
20
+
21
+
#### Repository configuration
22
+
23
+
- For outside collaborators, set permissions to read-only. 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.
24
+
25
+
#### Branch protection rules
26
+
27
+
Create the following branch protection rules using 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):
28
+
29
+
- Branch name pattern `**` with `Require signed commits` enabled.
30
+
- Branch name pattern matching only the default branch of the repository, such as `main`, with the following enabled:
31
+
-`Dismiss stale pull request approvals when new commits are pushed`
32
+
-`Required signed commits`
33
+
-`Do not allow bypassing the above settings`
34
+
35
+
#### Working with external contributors
36
+
37
+
When `allow-external-contributor` is set to `false`, external contributors can still contribute through the following workflow:
38
+
39
+
1. External contributors create pull requests as usual
40
+
2. A repository maintainer with COLLABORATOR, MEMBER, or OWNER status reviews the code
41
+
3. If the code is safe, the maintainer can:
42
+
43
+
- Approve and merge the pull request to another branch (workflows will run with maintainer permissions)
44
+
- Manually trigger workflow runs if needed (using workflow dispatch on the target branch)
45
+
46
+
This approach ensures that all code from external contributors is reviewed by trusted users before execution on self-hosted runners.
15
47
16
48
## Permission for GitHub app or personal access token
Copy file name to clipboardExpand all lines: docs/how-to/comply-security.md
+31-3Lines changed: 31 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,9 +2,29 @@
2
2
3
3
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.
4
4
5
-
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.
5
+
The charm provides the `allow-external-contributor` configuration option to control whether workflows triggered by external contributors can execute on the self-hosted runners. When set to `false`, only users with COLLABORATOR, MEMBER, or OWNER status can trigger workflows from pull requests, reviews, and comments.
6
6
7
-
In this guide, a recommended set of policies will be presented.
7
+
In this guide, a recommended set of policies and security practices will be presented.
8
+
9
+
## External contributor access control
10
+
11
+
Configure the charm to restrict external contributor access:
With this setting, workflows will only run for users with the following GitHub author associations:
18
+
- OWNER - Repository or organization owners
19
+
- MEMBER - Organization members
20
+
- COLLABORATOR - Users with explicit collaborator access
21
+
22
+
The charm checks author associations for these events:
23
+
-`pull_request` - Pull requests from external contributors
24
+
-`pull_request_target` - Pull request targeting (designed for handling PRs from forks)
25
+
-`pull_request_review` - Pull request reviews from external contributors
26
+
-`pull_request_review_comment` - Comments on pull request diffs from external contributors
27
+
-`issue_comment` - Comments on issues or pull requests from external contributors
8
28
9
29
## Recommended policy
10
30
@@ -20,4 +40,12 @@ With these settings, the common workflow of creating branches with pull requests
20
40
21
41
### Working with outside collaborators
22
42
23
-
Generally, outside collaborators are not completely trusted, but still would need to contribute in some manner. 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.
43
+
When `allow-external-contributor` is set to `false`, outside collaborators can still contribute through the following secure workflow:
44
+
45
+
1. External contributors create pull requests as usual
46
+
2. A repository maintainer with COLLABORATOR, MEMBER, or OWNER status reviews the code
47
+
3. If the code is safe, the maintainer can:
48
+
- Approve and merge the pull request to another branch (workflows will run with the permissions of the maintainer)
49
+
- Manually trigger workflow runs if needed (using workflow dispatch on the target branch)
50
+
51
+
This approach ensures that all code from external contributors is reviewed by trusted users before execution on self-hosted runners, eliminating the need for manual comment-based approval workflows.
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 their own single-use virtual machine instances. In addition, the charm provides security controls to ensure that code from external contributors is only executed when authorized.
4
+
5
+
The charm provides the `allow-external-contributor` configuration option to control whether workflows triggered by external contributors can execute on the self-hosted runners. When set to `false`, only users with COLLABORATOR, MEMBER, or OWNER status can trigger workflows.
6
+
7
+
In this guide, we'll explain how to configure external contributor access.
8
+
9
+
## External contributor access control
10
+
11
+
An external contributor is anyone whose GitHub author association is not OWNER, MEMBER, or COLLABORATOR. For internal pull requests (where the head and base repositories are the same), the association check is not applied; those runs are treated as internal.
12
+
13
+
The charm checks the GitHub author association for the following events that can be triggered by external contributors:
14
+
15
+
-`pull_request` - Pull requests from external contributors
16
+
-`pull_request_target` - Pull request targeting (designed for handling PRs from forks)
17
+
-`pull_request_review` - Pull request reviews from external contributors
18
+
-`pull_request_review_comment` - Comments on pull request diffs from external contributors
19
+
-`issue_comment` - Comments on issues or pull requests from external contributors
20
+
21
+
### Disable external contributor access
22
+
23
+
Prevent external contributors from triggering workflows. Run:
**Warning**: This setting allows any external contributor to trigger workflow execution on your self-hosted runners. Only use this in trusted environments or when you have other security controls in place.
0 commit comments