feat: custom_tarball param

Author: Justintime50

CHANGELOG.md

@@ -1,5 +1,10 @@
 # CHANGELOG
 
+## Next Release
+
+- Adds `custom_tarball` parameter, allowing you to bundle your distributable assets however you'd like
+- Optimizes how asset URL selection occurs when downloading assets to generate checksums for
+
 ## v3.1.0 (2025-12-26)
 
 - Adds `skip_checksum` parameter which skips uploading the checksum file for all release assets to the latest release. Useful if you generate your own checksums or already had a checksum file since we cannot overwrite an existing checksum file without deleting the previous one

README.md

@@ -33,6 +33,43 @@ When you cut a new release when using this GitHub Action, Homebrew Releaser will
 
 After you release a project on GitHub, Homebrew Releaser can publish that release to a personal Homebrew tap by updating the project description, version, tar archive url, license, checksum, installation and testing command, and any other required info so you don't have to. You can check the [Homebrew documentation on taps](https://docs.brew.sh/How-to-Create-and-Maintain-a-Tap) and the [formula cookbook](https://docs.brew.sh/Formula-Cookbook) for more details on setting up a Homebrew formula or tap.
 
+#### Minimal Setup
+
+The following is the bare minimum set of parameters required to run Homebrew Releaser (some defaults are assumed):
+
+```yml
+# .github/workflows/release.yml
+# Start Homebrew Releaser when a new GitHub release is created
+on:
+  release:
+    types: [published]
+
+jobs:
+  homebrew-releaser:
+    runs-on: ubuntu-latest
+    name: homebrew-releaser
+    steps:
+      - name: Release project to Homebrew tap
+        uses: Justintime50/homebrew-releaser@v3
+        with:
+          # The name of the homebrew tap to publish your formula to as it appears on GitHub (Homebrew taps must start with `homebrew-`).
+          # Required - strings
+          homebrew_owner: Justintime50
+          homebrew_tap: homebrew-formulas
+
+          # The Personal Access Token (saved as a repo secret) that has `repo` permissions for the repo running the action AND Homebrew tap you want to release to.
+          # Required - string
+          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+
+          # Install command for your formula.
+          # Required - string
+          install: 'bin.install "src/my-script.sh" => "my-script"'
+```
+
+#### Complete List of Parameters
+
+The following is the complete list of parameters that are usable with Homebrew Releaser:
+
 ```yml
 # .github/workflows/release.yml
 # Start Homebrew Releaser when a new GitHub release is created
@@ -109,7 +146,7 @@ jobs:
 
           # Adds URL and checksum targets for different OS and architecture pairs. Using this option assumes 
           # a tar archive exists on your GitHub repo with the following URL pattern (this cannot be customized):
-          # https://github.com/{GITHUB_OWNER}/{REPO_NAME}/releases/download/{TAG}/{REPO_NAME}-{VERSION}-{OPERATING_SYSTEM}-{ARCHITECTURE}.tar.gz'
+          # https://github.com/{github_owner}/{repo_name}/releases/download/{tag}/{repo_name}-{version}-{operating_system}-{architecture}.tar.gz'
           # Darwin AMD pre-existing path example: https://github.com/justintime50/myrepo/releases/download/v1.2.0/myrepo-1.2.0-darwin-amd64.tar.gz
           # Linux ARM pre-existing path example: https://github.com/justintime50/myrepo/releases/download/v1.2.0/myrepo-1.2.0-linux-arm64.tar.gz
           # Optional - booleans
@@ -118,6 +155,13 @@ jobs:
           target_linux_amd64: true
           target_linux_arm64: false
 
+          # Use a custom tarball on your release instead of the auto generated or templated arch URLs listed above.
+          # NOTE: Although you can use whatever packaging and naming conventions you want, Homebrew Releaser will look
+          # for your tarball at the following URL: https://github.com/{user}/{repo}/releases/download/{release_name}/{custom_tarball}.tar.gz
+          # Custom tarball pre-existing path example: https://github.com/justintime50/myrepo/releases/download/v1.2.0/v1.2.0.tar.gz
+          # Optional - string
+          custom_tarball: v1.2.0
+
           # Update your homebrew tap's README with a table of all projects in the tap.
           # This is done by pulling the information from all your formula.rb files - eg:
           #
@@ -149,7 +193,7 @@ jobs:
           debug: false
 ```
 
-#### Python
+#### Python Formula
 
 To release a Python package using Homebrew Releaser, one may setup their workflow like so:
 

action.yml

@@ -61,6 +61,9 @@ inputs:
   target_linux_arm64:
     description: 'Add a custom URL/checksum target for ARM64 Linux builds.'
     required: false
+  custom_tarball:
+    description: 'Use a custom tarball on your release instead of the auto generated or templated arch URLs listed above.'
+    required: false
   update_readme_table:
     description: "Update your homebrew tap's README with a table of all projects in the tap."
     required: false
@@ -95,6 +98,7 @@ runs:
     - ${{ inputs.target_darwin_arm64 }}
     - ${{ inputs.target_linux_amd64 }}
     - ${{ inputs.target_linux_arm64 }}
+    - ${{ inputs.custom_tarball }}
     - ${{ inputs.update_readme_table }}
     - ${{ inputs.skip_commit }}
     - ${{ inputs.skip_checksum }}

docker-compose.yml

@@ -27,4 +27,5 @@ services:
       - INPUT_TARGET_DARWIN_ARM64=
       - INPUT_TARGET_LINUX_AMD64=
       - INPUT_TARGET_LINUX_ARM64=
+      - INPUT_CUSTOM_TARBALL=
       - INPUT_SKIP_CHECKSUM=

homebrew_releaser/app.py

@@ -11,6 +11,7 @@
 from homebrew_releaser.constants import (
     CHECKSUM_FILE,
     CUSTOM_REQUIRE,
+    CUSTOM_TARBALL,
     DOWNLOAD_STRATEGY,
     FORMULA_INCLUDES,
     GITHUB_OWNER,
@@ -115,16 +116,16 @@ def run_github_action():
     if repository["private"]:
         logger.debug("Repository is private. Using auto-generated release tarball and zipball REST API endpoints.")
         archive_base_url = f"{GITHUB_BASE_URL}/repos/{GITHUB_OWNER}/{GITHUB_REPO}"
-        auto_generated_release_tar = f"{archive_base_url}/tarball/{version}"
-        auto_generated_release_zip = f"{archive_base_url}/zipball/{version}"
+        auto_generated_release_tar_url = f"{archive_base_url}/tarball/{version}"
+        auto_generated_release_zip_url = f"{archive_base_url}/zipball/{version}"
     else:
         logger.debug("Repository is public. Using auto-generated release tarball and zipball public URLs.")
         archive_base_url = f"https://github.com/{GITHUB_OWNER}/{GITHUB_REPO}/archive/refs/tags/{version}"
-        auto_generated_release_tar = f"{archive_base_url}.tar.gz"
-        auto_generated_release_zip = f"{archive_base_url}.zip"
+        auto_generated_release_tar_url = f"{archive_base_url}.tar.gz"
+        auto_generated_release_zip_url = f"{archive_base_url}.zip"
 
-    archive_urls.append(auto_generated_release_tar)
-    archive_urls.append(auto_generated_release_zip)
+    archive_urls.append(auto_generated_release_tar_url)
+    archive_urls.append(auto_generated_release_zip_url)
 
     target_browser_download_base_url = (
         f"https://github.com/{GITHUB_OWNER}/{GITHUB_REPO}/releases/download/{version}/{GITHUB_REPO}-{version_no_v}"
@@ -138,38 +139,42 @@ def run_github_action():
     if TARGET_LINUX_ARM64:
         archive_urls.append(f"{target_browser_download_base_url}-linux-arm64.tar.gz")
 
+    custom_tarball_url = None
+    if CUSTOM_TARBALL:
+        custom_tarball_url = (
+            f"https://github.com/{GITHUB_OWNER}/{GITHUB_REPO}/releases/download/{version}/{CUSTOM_TARBALL}.tar.gz"
+        )
+        logger.debug(
+            f"Using the following custom tarball URL instead of auto-generated tarball URL: {custom_tarball_url}"
+        )
+        archive_urls.append(custom_tarball_url)
+
     checksums = []
     for archive_url in archive_urls:
-        if not assets:
-            assets = [0]  # Populate `assets` so that if we don't have any, we can use the auto generated checksums
-        for asset in assets:
-            # Download the asset url so private repos work but use the brower URL for name and path in formula
-            if archive_url == auto_generated_release_tar or archive_url == auto_generated_release_zip:
-                download_url = archive_url
-            else:
-                download_url = asset["url"]
-
-            if (
-                archive_url == auto_generated_release_tar
-                or archive_url == auto_generated_release_zip
-                or archive_url == asset["browser_download_url"]
-            ):
-                # For REST API requests, we should not stream archive file, but it is fine for browser URLs
-                stream = False if archive_url.find("api.github.com") != -1 else True
-                downloaded_filename = _download_archive(download_url, stream)
-                checksum = calculate_checksum(downloaded_filename)
-                archive_filename = get_filename_from_path(archive_url)
-                archive_checksum_entries += f"{checksum} {archive_filename}\n"
-                checksums.append(
-                    {
-                        archive_filename: {
-                            "checksum": checksum,
-                            "url": archive_url,
-                        }
-                    },
-                )
-                # We break here so we don't include duplicate checksums for the auto generated URLs
-                break
+        if repository["private"]:
+            # For private repos, use asset["url"] if available, otherwise use archive_url
+            matching_asset = next(
+                (asset for asset in assets if asset and asset.get("browser_download_url") == archive_url), None
+            )
+            download_url = matching_asset["url"] if matching_asset else archive_url
+            stream = False
+        else:
+            # For public repos, always use browser URLs
+            download_url = archive_url
+            stream = True
+
+        downloaded_filename = _download_archive(download_url, stream)
+        checksum = calculate_checksum(downloaded_filename)
+        archive_filename = get_filename_from_path(archive_url)
+        archive_checksum_entries += f"{checksum} {archive_filename}\n"
+        checksums.append(
+            {
+                archive_filename: {
+                    "checksum": checksum,
+                    "url": archive_url,
+                }
+            }
+        )
 
     write_file(CHECKSUM_FILE, archive_checksum_entries)
 
@@ -180,7 +185,7 @@ def run_github_action():
         repository,
         checksums,
         INSTALL,
-        auto_generated_release_tar,
+        custom_tarball_url or auto_generated_release_tar_url,
         DEPENDS_ON,
         TEST,
         DOWNLOAD_STRATEGY,

homebrew_releaser/constants.py

@@ -58,3 +58,4 @@
 TARGET_LINUX_ARM64 = (
     os.getenv("INPUT_TARGET_LINUX_ARM64", False) if os.getenv("INPUT_TARGET_LINUX_ARM64") != "false" else False
 )  # Must check for string `false` since GitHub Actions passes the bool as a string
+CUSTOM_TARBALL = os.getenv("INPUT_CUSTOM_TARBALL")

homebrew_releaser/formula.py

@@ -10,6 +10,7 @@
 
 from homebrew_releaser.constants import (
     ARTICLES,
+    CUSTOM_TARBALL,
     LOGGER_NAME,
     MAX_DESC_FIELD_LENGTH,
     TARGET_DARWIN_AMD64,
@@ -90,23 +91,29 @@ def generate_formula_data(
     for index, checksum in enumerate(checksums):
         checksum_filename = next(iter(checksum))
         checksum_url = checksum[checksum_filename]["url"]  # type: ignore
+        checksum_value = checksum[checksum_filename]["checksum"]  # type: ignore
 
-        # Autogenerated tar URL is the first one
+        # Autogenerated tar URL is always the first entry
         if index == 0:
-            autogenerated_tar_checksum = checksum[checksum_filename]["checksum"]  # type: ignore
+            tar_url_checksum = checksum_value  # type: ignore
+            continue
+
+        # If using a custom tarball, replace the tar_url_checksum with that one
+        if CUSTOM_TARBALL and re.search(rf".*/download/[^/]+/{re.escape(CUSTOM_TARBALL)}\.tar\.gz$", checksum_url):
+            tar_url_checksum = checksum_value  # type: ignore
 
         if checksum_url.endswith("darwin-amd64.tar.gz") and TARGET_DARWIN_AMD64:
             darwin_amd64_url = checksum_url
-            darwin_amd64_checksum = checksum[checksum_filename]["checksum"]  # type: ignore
+            darwin_amd64_checksum = checksum_value  # type: ignore
         elif checksum_url.endswith("darwin-arm64.tar.gz") and TARGET_DARWIN_ARM64:
             darwin_arm64_url = checksum_url
-            darwin_arm64_checksum = checksum[checksum_filename]["checksum"]  # type: ignore
+            darwin_arm64_checksum = checksum_value  # type: ignore
         elif checksum_url.endswith("linux-amd64.tar.gz") and TARGET_LINUX_AMD64:
             linux_amd64_url = checksum_url
-            linux_amd64_checksum = checksum[checksum_filename]["checksum"]  # type: ignore
+            linux_amd64_checksum = checksum_value  # type: ignore
         elif checksum_url.endswith("linux-arm64.tar.gz") and TARGET_LINUX_ARM64:
             linux_arm64_url = checksum_url
-            linux_arm64_checksum = checksum[checksum_filename]["checksum"]  # type: ignore
+            linux_arm64_checksum = checksum_value  # type: ignore
 
     # We set these so we can properly space items only if both are present
     darwin_amd_and_arm = darwin_amd64_url and darwin_arm64_url
@@ -134,7 +141,7 @@ class {{class_name}} < Formula
   {{# version}}
   version "{{version}}"
   {{/ version}}
-  sha256 "{{autogenerated_tar_checksum}}"
+  sha256 "{{tar_url_checksum}}"
   {{# license_type}}
   license "{{license_type}}"
   {{/ license_type}}
@@ -204,7 +211,7 @@ def install
         "owner": owner,
         "repo_name": repo_name,
         "tar_url": tar_url,
-        "autogenerated_tar_checksum": autogenerated_tar_checksum,
+        "tar_url_checksum": tar_url_checksum,
         "license_type": license_type,
         "dependencies": dependencies_list,
         "install_instructions": _match_indent_of(template, "install_instructions", install),

test/formulas/test_generate_formula_custom_tarball.rb

@@ -0,0 +1,15 @@
+# typed: true
+# frozen_string_literal: true
+
+# This file was generated by Homebrew Releaser. DO NOT EDIT.
+class TestGenerateFormulaCustomTarball < Formula
+  desc "Release scripts, binaries, and executables to github"
+  homepage "https://github.com/Justintime50/test-generate-formula-custom-tarball"
+  url "https://github.com/Justintime50/test-generate-formula-custom-tarball/download/v0.1.0/custom_tarball.tar.gz"
+  sha256 "0000000000000000000000000000000000000000000000000000000000000000"
+  license "MIT"
+
+  def install
+    bin.install "src/secure-browser-kiosk.sh" => "secure-browser-kiosk"
+  end
+end