gha-trigger - Webhook Server and Actions for Secure GitHub Actions

Today, gha-trigger v0.1.0 has been released. In this post, I introduce gha-trigger.

What's gha-trigger?

gha-trigger is Webhook Server and Actions to run GitHub Actions securely.
It prevents Workflows and scripts from being modified and running malicious commands.

Background

GitHub Actions is very powerful CI Platform, but also has a security risk that someone modifies workflows and workflow 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

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.

GitHub Actions

We provide some GitHub Actions for gha-trigger.

• start-action
  • set-env-action
  • commit-status-action
• end-action
  • commit-status-action
• step-summary-action

gha-trigger's Workflow is different from normal GitHub Actions Workflow, so you have to do some additional tasks.
For example, you have to update commit statuses yourself.

These actions do the common tasks and let you concentrate on the main workflow implementation.

• Show how to rerun and cancel workflow in GITHUB_STEP_SUMMARY
• Set useful Environment Variables
• Generate GitHub App Token
• Update commit statuses
• Checkout Main Repository and CI Repository

For the detail, please see the document.

How to use

You have to create GitHub repositories, GitHub Apps, and AWS resources such as Amazon API Gateway, AWS Lambda, AWS SecretsManager, and so on.

Please see Getting Started.

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

Conclusion

In this post, I introduce gha-trigger, which is Webhook Server and Actions to run GitHub Actions securely.

For the detail, please see the official document.

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