Skip to main content

Getting Started

In the Getting Started, you will set up gha-trigger and experience CI with gha-trigger.

Requirement​

Steps​

  1. Create GitHub Repositories from template repositories
  2. Create Webhook Secret
  3. Set up Terraform Configuration
  4. Apply Terraform
  5. Create GitHub Apps
  6. Set GitHub App ID and Private Key
  7. Apply Terraform again
  8. Run Manual Workflow
  9. Clean up

1. Create GitHub Repositories from template repositories​

And checkout them.

Create the remote branch pull_request in CI Repository.​

This branch is used to run Workflows via pull_request event.

$ git checkout -b pull_request
$ git push origin pull_request

3. Set up Terraform Configuration​

$ git clone https://github.com/gha-trigger/example-terraform
$ cd example-terraform
$ bash download-zip.sh # Download a zip file from Release page

Create some files from templates.

$ cp config.yaml.tmpl config.yaml
$ vi config.yaml # Fix Repository owner and name

$ cp secret.yaml.tmpl secret.yaml
$ vi secret.yaml # Set GitHub App Webhook Secret

$ cp secret_trigger_workflow.yaml.tmpl secret_trigger_workflow.yaml

GitHub Apps aren't created yet, so please set dummy strings as GitHub App ID and Private keys at the moment.

4. Apply Terraform​

Create resources.

$ terraform init
$ terraform validate
$ terraform apply
caution

Amazon API Gateway is published at the internet and everyone can access it. gha-trigger validates requests so it is dificult for malicious people to run workflows without GitHub Webhook, but it has a risk of DDos Attack. We recommend to delete the endpoint soon when the getting started has been finished.

5. Create GitHub Apps​

Please create GitHub Apps according to the document.

  • Create GitHub App
  • Create Private Key
  • Set Permissions & events
  • Install GitHub App to repositories

6. Set GitHub App ID and Private Key​

  • GitHub Repository Secret
    • CI Repository
      • APP_ID: GitHub App ID of Trigger CI Workflow App
      • APP_PRIVATE_KEY: GitHub App Private Key of Trigger CI Workflow App
    • Manual Workflow Repository
      • APP_ID: GitHub App ID of Manual Workflow App
      • APP_PRIVATE_KEY: GitHub App Private Key of Manual Workflow App
  • config.yaml
    • app_id
  • secret.yaml
    • github_app_private_key: GitHub App Private Key of Webhook App
  • secret_trigger_workflow.yaml
    • github_app_private_key: GitHub App Private Key of Trigger CI Workflow App

7. Apply Terraform again​

After setting GitHub App ID and Private Key, run terraform apply again.

$ terraform apply

8. Run Manual Workflow​

You can create a pull request to Main Repository without Manual Workflow, but in the getting started let's run Manual Workflow.

$ gh workflow run scaffold.yaml -f service=foo

Then create a pull request according to the guide in GitHub Actions Step Summary.

CI would work in CI Repository via gha-trigger. If CI doesn't work well, please check Lambda Log.

10. Clean up​

$ terraform destroy