I started a new job in July 2022. While the developer experience is great, one of the things that I missed at my new job was a CLI (like I had at my old job). I thought of building an easily extensible CLI tool which I did with and cobra. To handle distribution to the engineers, we decided to use both and . to rule them all go go install homebrew Homebrew is a very popular package manager for macOS and . Users can easily install new packages with . Homebrew handles the downloading and the installation of the packages to the appropriate directories and then creates symlinks to (on Intel machines). Linux users brew install [PACKAGE] /usr/local To create a Homebrew package, we create Ruby classes called . A Formula looks like this: Formulas class Wget < Formula
  homepage "https://www.gnu.org/software/wget/"
  url "https://ftp.gnu.org/gnu/wget/wget-1.15.tar.gz"
  sha256 "52126be8cf1bddd7536886e74c053ad7d0ed2aa89b4b630f76785bac21695fcd"

  def install
    system "./configure", "--prefix=#{prefix}"
    system "make", "install"
  end
end While adding an open-source package is fairly straightforward, doing the same with a private package involves a bit of hacking. First Steps The first thing to do is create a Github release, if you use , I highly recommend using I wrote a tutorial on how to do that . It truly makes releases in easy. If you're using another language, you should check out how to manage releases in GitHub . go . goreleaser here go here Create a Homebrew Tap The next thing to do is to create a . A Homebrew tap is a GitHub repository that houses our Formulas. To add non-Homebrew core taps, we need to add the taps locally to homebrew with . Homebrew tap brew tap username/package For us to use the single argument form of , we need to follow the and name our GitHub repo since the GitHub repo must start with . brew tap naming convention homebrew-tap homebrew- Create a Formula If you have a release already in Github, we can go ahead with creating the Formula. In our repo, we'll create a folder called . In the directory, we'll create a file called . homebrew-tap Formula Formula mytool.rb Now, in our , we cannot use the standard way of downloading the packages since our package is hosted in a private repo. To do this we simply add a new download strategy like such: Formula require "formula"
require_relative "../custom_download_strategy.rb"

class Wget < Formula
  homepage "https://www.gnu.org/software/wget/"
  url "https://ftp.gnu.org/gnu/wget/wget-1.15.tar.gz", :using => GitHubPrivateRepositoryReleaseDownloadStrategy 
  sha256 "52126be8cf1bddd7536886e74c053ad7d0ed2aa89b4b630f76785bac21695fcd"

  def install
    system "./configure", "--prefix=#{prefix}"
    system "make", "install"
  end

  test do
      system "#{bin}/wget --help"
  end
end Note the addition of on the third line of the class. , :using => GitHubPrivateRepositoryReleaseDownloadStrategy In the root folder of , we'll create a new file called . Here, we'll add some code to support our download strategy. homebrew-tap custom_download_strategy.rb require "download_strategy"

class GitHubPrivateRepositoryDownloadStrategy < CurlDownloadStrategy
  require "utils/formatter"
  require "utils/github"

  def initialize(url, name, version, **meta)
    super
    parse_url_pattern
    set_github_token
  end

  def parse_url_pattern
    unless match = url.match(%r{https://github.com/([^/]+)/([^/]+)/(\S+)})
      raise CurlDownloadStrategyError, "Invalid url pattern for GitHub Repository."
    end

    _, @owner, @repo, @filepath = *match
  end

  def download_url
    "https://#{@github_token}@github.com/#{@owner}/#{@repo}/#{@filepath}"
  end

  private

  def _fetch(url:, resolved_url:, timeout:)
    curl_download download_url, to: temporary_path, timeout: timeout
  end

  def set_github_token
    @github_token = ENV["HOMEBREW_GITHUB_API_TOKEN"]
    unless @github_token
      raise CurlDownloadStrategyError, "Environmental variable HOMEBREW_GITHUB_API_TOKEN is required."
    end

    validate_github_repository_access!
  end

  def validate_github_repository_access!
    # Test access to the repository
    GitHub.repository(@owner, @repo)
  rescue GitHub::HTTPNotFoundError
    # We only handle HTTPNotFoundError here,
    # becase AuthenticationFailedError is handled within util/github.
    message = <<~EOS
      HOMEBREW_GITHUB_API_TOKEN can not access the repository: #{@owner}/#{@repo}
      This token may not have permission to access the repository or the url of formula may be incorrect.
    EOS
    raise CurlDownloadStrategyError, message
  end
end

# GitHubPrivateRepositoryReleaseDownloadStrategy downloads tarballs from GitHub
# Release assets. To use it, add
# `:using => GitHubPrivateRepositoryReleaseDownloadStrategy` to the URL section of
# your formula. This download strategy uses GitHub access tokens (in the
# environment variables HOMEBREW_GITHUB_API_TOKEN) to sign the request.
class GitHubPrivateRepositoryReleaseDownloadStrategy < GitHubPrivateRepositoryDownloadStrategy
  def initialize(url, name, version, **meta)
    super
  end

  def parse_url_pattern
    url_pattern = %r{https://github.com/([^/]+)/([^/]+)/releases/download/([^/]+)/(\S+)}
    unless @url =~ url_pattern
      raise CurlDownloadStrategyError, "Invalid url pattern for GitHub Release."
    end

    _, @owner, @repo, @tag, @filename = *@url.match(url_pattern)
  end

  def download_url
    "https://#{@github_token}@api.github.com/repos/#{@owner}/#{@repo}/releases/assets/#{asset_id}"
  end

  private

  def _fetch(url:, resolved_url:, timeout:)
    # HTTP request header `Accept: application/octet-stream` is required.
    # Without this, the GitHub API will respond with metadata, not binary.
    curl_download download_url, "--header", "Accept: application/octet-stream", to: temporary_path, timeout: timeout
  end

  def asset_id
    @asset_id ||= resolve_asset_id
  end

  def resolve_asset_id
    release_metadata = fetch_release_metadata
    assets = release_metadata["assets"].select { |a| a["name"] == @filename }
    raise CurlDownloadStrategyError, "Asset file not found." if assets.empty?

    assets.first["id"]
  end

  def fetch_release_metadata
    GitHub.get_release(@owner, @repo, @tag)
  end
end We should have the following folder structure: ├── homebrew-tap
│   ├── Formula
│   │   ├── mytool.rb
└── custom_download_strategy.rb Usage We're almost done. To install our tool via Homebrew, we need to export a Github token that provides access to our private repos. A new token can be created . The token needs to have permissions. We need to export the token as . To export the token, we run: here repo HOMEBREW_GITHUB_API_TOKEN export HOMEBREW_GITHUB_API_TOKEN=<GITHUB_TOKEN>
# if you're using fish shell like me, run `set -x HOMEBREW_GITHUB_API_TOKEN <GITHUB_TOKEN>` Then, we can run the command: brew install username/homebrew-tap/mytool This automatically adds the homebrew tap and installs our tool. Summary Create a GitHub release with the binaries. This can be done very easily with in the case of . goreleaser go Create a GitHub repo called . An example is . homebrew-tap here Create a folder. Formula In the root of the repo, create a file called . The contents are shown above custom_download_strategy.rb In the folder, create a ruby file with the name of your tool like Formula mytool.rb Create a GitHub token and give permissions to the token. repo Export the token with export HOMEBREW_GITHUB_API_TOKEN=<GITHUB_TOKEN> Install the tool with brew using . brew install username/homebrew-tap/mytool Also published here.

Building Homebrew Taps for Private GitHub Repos

Too Long; Didn't Read

Companies Mentioned

Coin Mentioned

@damilare

RELATED STORIES