Skip to main content

gha-trigger

License

https://github.com/gha-trigger/gha-trigger

Webhook Server for Secure GitHub Actions

⚠️ Deprecated. Please use pull_request_target instead​

Secure GitHub Actions by pull_request_target

Goal​

Run GitHub Actions Workflow securely. Prevent GitHub Actions Workflow from being modified and running malicious commands.

Background​

GitHub Actions is very powerful CI Platform, but also has a security risk that someone modifies workflow and CI scripts and run malicious commands. For example, secrets with strong permission may be abused and stolen.

GitHub provides several features such as CODEOWNERS, branch protection rule, OIDC Support, and so on, but they can't solve the above threat perfectly.

You can use other CI Platform to prevent workflows from being modified, but we would like to use GitHub Actions because GitHub Actions is very powerful.

So we design the architecture and develop gha-trigger to achieve the above goal.

Architecture​

gha-trigger drawio

You create two GitHub repositories.

  • Main Repository
    • Users develop this repository
    • Disable GitHub Actions
  • CI Repository
    • Manage GitHub Actions Workflows and CI scripts
    • Only CI maintainers have write permissiono and other users have only read permission

When events such as push and pull_request occur in Main Repository, the webhook is sent to gha-trigger. gha-trigger validates and filters webhooks and triggers GitHub Actions Workflows of CI Repository via GitHub API. Workflows of CI Repository update commit statuses of Main Repository and send pull request comments so that users can refer CI results from Main Repository's pull request pages.

The important thing is that workflows and CI scripts are managed at the repository other than Main Repository and only restricted people have the write permission of CI Repository. This prevents users from modifying workflows and CI scripts and makes GitHub Actions secure.

gha-trigger supports multiple pairs of Main Repository and CI Repository. You can also share CI Repository for multiple Main Repository.

How to rerun and cancel CI​

Users don't have the write permission of CI Repository, so they can't rerun and cancel workflows directly. But they can rerun and cancel workflows via pull request comments.

image

  • Rerun workflows: /rerun-workflow <workflow run id> [<workflow run id> ...]
  • Rerun failed jobs: /rerun-failed-jobs <workflow run id> [<workflow run id> ...]
  • Cancel workflows: /cancel <workflow run id> [<workflow run id> ...]

gha-trigger guides commands by $GITHUB_STEP_SUMMARY.

e.g.

image

How to trigger workflows manually​

If you would like to add workflows that users run manually, you have to create a repository for those workflows.

For detail, please see Manual Workflow.

GitHub Actions​

We provide some GitHub Actions for gha-trigger. Please see GitHub Actions.

Supported Platforms​

gha-trigger supports only AWS Lambda at the moment, but we're considering to support other platform such as Google Cloud Function too.

Supported Events​

gha-trigger aims to support all events that GitHub Actions supports.

For detail, please see Supported Events.

Pros and Cons​

Pros​

The pros of gha-trigger is that you can run GitHub Actions securely. You can prevent GitHub Actions Workflow from being modifying and running malicious commands.

Cons​

Compared with normal GitHub Actions usage, gha-trigger has some drawbacks.

Release Notes​

Please see each repository's GitHub Releases.

LICENSE​

MIT