Securely Merging Pull Requests from Public Contributors

Maintaining secure workflows for pull requests originating from public forks on GitHub poses unique challenges. These untrusted repositories lack elevated permissions, making it risky to grant access to sensitive data. The SOURCE material outlines three strategies to mitigate these risks when handling secret-dependent workflows, such as tests, in an untrusted forked pull request context.

The first approach, using the pull_request_target event, was introduced in 2021. This method raises the GITHUB_TOKEN permissions to read/write for forked pull requests. The context switches to the base repository instead of the fork, allowing non-intrusive tasks like automated labels and comments to run securely within a trusted setting.

However, secret-dependent workflows still fail in this setup, as they operate from the perspective of the proposed code changes rather than the base repository. Nonetheless, this method is not recommended for running or building untrusted code. Developers should carefully review the associated warnings and precautions from GitHub's official documentation.

The second solution involves utilizing the workflow_run event to create a prescan workflow. This two-step process begins with a workflow triggered by the pull_request event. This prescan workflow performs static analysis of the untrusted code and only runs without any secrets access. Once the prescan workflow successfully completes, a second workflow is triggered through a workflow_run event.

This second workflow receives secrets access, enabling it to perform secret-dependent tasks such as running tests on the proposed code changes in the forked repository. To enhance security, this prescan workflow should fail if the author is identified as untrusted based on comparisons or if sensitive files have been altered. Additionally, the use of CodeQL should be monitored to ensure comprehensive security checks.

The third and preferred solution is to employ isolated, disposable environments for running tests. After a successful prescan workflow, developers can clone the code into an isolated, disposable environment. This approach minimizes the risk of exposing sensitive data and ensures that tests are run locally, providing more control over the environment.

Best practices for this method include requiring contributors to obtain their own test secrets if accessible, running tests locally, and sharing screenshots of the results in the PR template. It is crucial to document these processes in the repository's README and CONTRIBUTING files. Maintainers should also approve workflow runs on forks, and secrets should never be exposed directly in a pull_request_target workflow checking out PR code.

Instead, dummy secrets with limited permissions should be used and regularly monitored. Additionally, any untrusted data should be prevented from influencing prescan workflow logic, and script injections should be avoided by preferring GitHub Actions over inline scripts. The SOURCE material emphasizes the importance of pinning marketplace Actions versions with commit SHAs and staying updated on security measures.