Triggers on pushes to the main branch

Oct 13, 2025 by wbrum.org 140 views

Overview

In this article, we will outline the requirements for a reusable GitHub Action to automatically update Homebrew formula when a project is released. This action will be designed to be reusable across multiple projects, allowing for easy integration and customization.

Background

We've implemented a GitHub Actions workflow in the cajias/zi repository that automatically updates a Homebrew formula in the cajias/homebrew-tools repository whenever changes are pushed to the main branch. However, we want to extract this pattern into a reusable GitHub Action that can be used across multiple projects.

Current Implementation

The current workflow (.github/workflows/update-homebrew-tap.yml) does the following:

Triggers on pushes to the main branch: The workflow is triggered when changes are pushed to the main branch.
Creates a versioned release tag: A versioned release tag is created based on the date and commit hash.
Creates a GitHub Release: A GitHub Release is created with the new version and SHA256.
Checks out the homebrew-tools repository: The homebrew-tools repository is checked out.
Updates the formula with the new version and SHA256: The formula is updated with the new version and SHA256.
Commits and pushes the changes to the homebrew-tools repository: The changes are committed and pushed to the homebrew-tools repository.

Requirements for the Reusable Action

Input Parameters

The reusable action will require the following input parameters:

github_token: A GitHub token with appropriate permissions.
tap_repo_token: A token with write access to the Homebrew tap repository.
github_user: The GitHub username of the repository owner.
source_repo: The repository containing the source code.
tap_repo: The repository containing the Homebrew tap.
formula_name: The name of the formula file to update.
formula_path: The path to the formula file within the tap repository.
version_strategy: The strategy for generating the version (date-based, semver, etc.).
paths_to_watch: The files that trigger the workflow when changed.
custom_release_notes: Optional custom release notes template.

Functionality

The reusable action will provide the following functionality:

Version Generation: Support different versioning strategies (date-based, semver from tags, etc.) and allow for custom version formatting.
Release Creation: Create appropriate tags based on the versioning strategy and generate GitHub releases with customizable notes.
Formula Update: Calculate SHA256 for the release tarball, update version, URL, and SHA256 in the formula, and support custom formula templates.
Commit & Push: Commit changes to the tap repository with appropriate commit messages and handle authentication securely.

Repository Structure

The action will be implemented in the cajias/custom-github-actions repository with:

Main action implementation
Documentation with examples
Test workflows for validation
Reusable templates

Examples

Example workflow using the action:

name: Update Homebrew Formula

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
  workflow_dispatch:

jobs:
  update-homebrew:
    runs-on: ubuntu-latest
    steps:
      - uses: cajias/custom-github-actions/update-homebrew@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          tap_repo_token: ${{ secrets.TAP_REPO_TOKEN }}
          github_user: username
          source_repo: my-project
          tap_repo: homebrew-tools
          formula_name: my-formula
          formula_path: Formula/my-formula.rb
          version_strategy: date-commit

Additional Considerations

Security best practices for handling tokens: The action will need to handle tokens securely to prevent unauthorized access.
Error handling and reporting: The action will need to handle errors and report them in a way that is easy to understand.
Testing across different environments: The action will need to be tested across different environments to ensure it works as expected.
Documentation for setup and usage: The action will need to have clear documentation for setup and usage to make it easy for users to integrate it into their workflows.

Q: What is the purpose of the reusable GitHub Action?

A: The purpose of the reusable GitHub Action is to automatically update Homebrew formula when a project is released. This action will be designed to be reusable across multiple projects, allowing for easy integration and customization.

Q: What are the input parameters required for the reusable action?

A: The reusable action requires the following input parameters:

github_token: A GitHub token with appropriate permissions.
tap_repo_token: A token with write access to the Homebrew tap repository.
github_user: The GitHub username of the repository owner.
source_repo: The repository containing the source code.
tap_repo: The repository containing the Homebrew tap.
formula_name: The name of the formula file to update.
formula_path: The path to the formula file within the tap repository.
version_strategy: The strategy for generating the version (date-based, semver, etc.).
paths_to_watch: The files that trigger the workflow when changed.
custom_release_notes: Optional custom release notes template.

Q: What are the functionality provided by the reusable action?

A: The reusable action provides the following functionality:

Version Generation: Support different versioning strategies (date-based, semver from tags, etc.) and allow for custom version formatting.
Release Creation: Create appropriate tags based on the versioning strategy and generate GitHub releases with customizable notes.
Formula Update: Calculate SHA256 for the release tarball, update version, URL, and SHA256 in the formula, and support custom formula templates.
Commit & Push: Commit changes to the tap repository with appropriate commit messages and handle authentication securely.

Q: How do I set up the reusable action in my GitHub repository?

A: To set up the reusable action in your GitHub repository, follow these steps:

Create a new GitHub repository for your project.
Create a new file in the .github/workflows directory called update-homebrew.yml.
Copy the example workflow code from the documentation and paste it into the update-homebrew.yml file.
Update the input parameters to match your project's requirements.
Save the file and commit the changes to your repository.

Q: How do I customize the reusable action for my project?

A: To customize the reusable action for your project, follow these steps:

Update the input parameters to match your project's requirements.
Customize the versioning strategy to suit your project's needs.
Update the formula template to match your project's requirements.
Add custom release notes template to provide additional information about the release.

Q: How do I troubleshoot issues with the reusable action?

A: To troubleshoot issues with the reusable action, follow these steps:

Check the GitHub Actions logs for errors or warnings.
Verify that the input parameters are correct and up-to-date.
Check the formula template for any errors or inconsistencies.
Reach out to the GitHub community or the action's maintainers for assistance.

Q: How do I contribute to the reusable action?

A: To contribute to the reusable action, follow these steps:

Fork the action's repository on GitHub.
Make changes to the code to improve the action's functionality or fix bugs.
Submit a pull request to the action's maintainers for review and approval.
Participate in the GitHub community to provide feedback and suggestions for future improvements.