DOCSEARCHbyAlgolia
Submit Docs

gha-trigger

website·Indexed 30 days ago

https://gha-trigger.github.io

A tool designed to trigger GitHub Actions workflows, featuring an architecture based on AWS Lambda and support for various GitHub events. The documentation covers setup, configuration via environment variables and AWS Secrets Manager, and the use of GitHub Apps for token issuance in CI.

Tokens
4.2K
Snippets
18
Records
28
Agent score
74%

What's inside gha-trigger

  1. Understand gha-trigger GitHub API rate limit mitigation

    To prevent GitHub API rate limiting and ensure scalability, gha-trigger minimizes API calls. This design choice results in specific trade-offs regarding the level of detail available in certain outputs:

    1. Workflow Run URLs: Instead of providing a specific Job URL (which would require an API call to retrieve the Job ID), gha-trigger provides the broader workflow run URL: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID.
    2. GHA_SHA Availability: For certain GitHub events (such as release), gha-trigger does not set the GHA_SHA variable because retrieving the default branch's commit hash would require an additional API call.

  2. Secure GitHub Actions using gha-trigger architecture

    gha-trigger prevents malicious modification of CI scripts by splitting the environment into two repositories: a Main Repository (where users develop and GitHub Actions are disabled) and a CI Repository (where workflows and scripts are managed and only maintainers have write access). When events occur in the Main Repository, gha-trigger validates the webhook and triggers the corresponding workflow in the CI Repository via the GitHub API. Results are then reported back to the Main Repository via commit statuses and PR comments.

  3. Implement asynchronous AWS Lambda invocation for GitHub Webhooks

    GitHub requires integrations to respond to webhook payloads within 10 seconds. To avoid timeouts, gha-trigger must be invoked asynchronously. This is achieved by using Amazon API Gateway to trigger the AWS Lambda function. Note that AWS Lambda Function URLs are not used for this purpose because they do not support asynchronous invocation in the required manner.

  4. Implement a gha-trigger workflow using start-action and end-action

    Because gha-trigger workflows differ from standard GitHub Actions, you must use specific actions to handle common tasks like updating commit statuses, generating GitHub App tokens, and setting environment variables.

    Key components:

    • gha-trigger/start-action: Initializes the job, generates a GitHub App token, and sets environment variables.
    • gha-trigger/end-action: Finalizes the job and updates the commit status based on the job result.
    • gha-trigger/step-summary-action: Generates a summary in GITHUB_STEP_SUMMARY showing how to rerun or cancel the workflow.
    jobs:
  gha-trigger-summary:
    runs-on: ubuntu-latest
    steps:
      - uses: gha-trigger/step-summary-action@v0.1.1
        with:
          data: ${{inputs.data}}

  test:
    runs-on: ubuntu-latest
    steps:
      - uses: gha-trigger/start-action@v0.1.6
        id: start
        with:
          data: ${{inputs.data}}
          app_id: ${{secrets.APP_ID}}
          app_private_key: ${{secrets.APP_PRIVATE_KEY}}

      # Add your custom steps here

      - uses: gha-trigger/end-action@v0.1.3
        if: always()
        with:
          github_token: ${{steps.start.outputs.github_app_token}}
          state: ${{job.status}}

  5. Configure and deploy gha-trigger infrastructure with Terraform

    Deploy the gha-trigger infrastructure using the provided Terraform example.

    1. Clone the Terraform repository and download the necessary zip files.
    2. Initialize configuration files from templates. You must edit config.yaml to set the repository owner and name, and secret.yaml to set the GitHub App Webhook Secret.
    3. Use dummy strings for GitHub App ID and Private keys during the initial deployment.
    4. Run the Terraform apply process.

    Caution: The Amazon API Gateway endpoint is public. While gha-trigger validates requests, the endpoint is susceptible to DDoS attacks. Delete the endpoint immediately after completing the setup.

    # Setup configuration
git clone https://github.com/gha-trigger/example-terraform
cd example-terraform
bash download-zip.sh

cp config.yaml.tmpl config.yaml
# Edit config.yaml: Fix Repository owner and name

cp secret.yaml.tmpl secret.yaml
# Edit secret.yaml: Set GitHub App Webhook Secret

cp secret_trigger_workflow.yaml.tmpl secret_trigger_workflow.yaml

# Deploy infrastructure
terraform init
terraform validate
terraform apply

  6. Manage OIDC permissions using CI Repository branches

    When using OpenID Connect (OIDC) with GitHub Actions, you can manage different permission levels based on the triggering event by creating dedicated branches in your CI Repository. For example, to restrict permissions for pull requests, create a pull_request branch and configure the workflow to run from that branch. This allows the workflow to assume a specific AWS IAM Role with restricted (e.g., read-only) permissions, ensuring that PR-triggered actions cannot perform privileged operations.

  7. Authenticate to Main Repository using GitHub App Token

    To access the Main Repository (as opposed to the CI Repository), you cannot use the default ${{ github.token }}. You must use a GitHub App Token generated by gha-trigger/start-action via its github_app_token output.
    - uses: gha-trigger/start-action@v0.1.6
  id: start
  with:
    data: ${{inputs.data}}
    app_id: ${{secrets.APP_ID}}
    app_private_key: ${{secrets.APP_PRIVATE_KEY}}

- name: Add a Pull Request Label
  run: gh pr edit -R "${{env.GHA_REPOSITORY}}" "$PR_NUMBER" --add-label "help wanted"
  env:
    GITHUB_TOKEN: ${{steps.start.outputs.github_app_token}}

  9. Handle gha-trigger workflow dispatch inputs

    When gha-trigger triggers a workflow via the workflow_dispatch API, it passes a JSON string in the data input. This string must be parsed using the fromJSON() expression to access specific fields. The data object contains:

    • event: The full webhook event payload.
    • event_name: The name of the event (e.g., push, pull_request).
    • changed_files: A list of changed files (up to 3000 files due to API limits), available only when paths filters are used.
    • pull_request: Pull request data (for pull_request events, gha-trigger waits until mergeable is not null before setting this field).
    on:
  workflow_dispatch:
    inputs:
      data:
        required: true

jobs:
  example-job:
    runs-on: ubuntu-latest
    env:
      PR_NUMBER: ${{ fromJSON(inputs.data).event.pull_request.number }}

  11. Set up a dedicated repository for manual GitHub Action workflows

    To allow users to run workflows manually (e.g., for scaffolding pull requests), create a separate repository (a 'Manual Workflow Repository') distinct from your 'Main Repository'.

    Key requirements for this setup:

    1. GitHub App Installation: Install the required GitHub App in both the Main Repository and the Manual Workflow Repository to enable cross-repository access.
    2. User Permissions: Users must be granted write permission to the Manual Workflow Repository to trigger workflows.
    3. Security Constraint: To prevent users from bypassing review processes, the GitHub App should be configured with permission to push commits to the Main Repository, but NOT to create or merge pull requests. Workflows should create feature branches in the Main Repository, requiring users to manually open the pull requests themselves.

  12. Set up gha-trigger repositories and environment

    Initialize the environment by creating repositories from the following templates and checking them out:

    • Main Repository
    • CI Repository
    • Manual Workflow Repository

    To enable workflows via the pull_request event, you must create a remote branch named pull_request in the CI Repository.

    # Create and push the pull_request branch in the CI Repository
git checkout -b pull_request
git push origin pull_request