jreleaser.github.io/docs/modules/configuration/pages/packagers/homebrew.adoc

= Homebrew

The `brew` section specifies how the formula should be created. You can check the
link:https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md[Homebrew documentation] and the
link:https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md[formula cookbook] for more details.

NOTE: Only artifacts with `.zip`, `.jar` extension may be packaged with Homebrew.

WARNING: Snapshots are *not* supported.

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:dot-circle[]
packagers:
  # icon:dot-circle[]
  brew:
    # Enables or disables Homebrew.
    # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `NEVER`.
    # icon:dot-circle[]
    active: ALWAYS

    # Directory with file templates used to prepare the Homebrew distribution
    # Defaults to `src/distribution/${distribution.name}/brew`.
    # If specified, path must exist.
    # icon:dot-circle[]
    templateDirectory: path/to/brew/templates

    # The class name of the generated formula.
    # If left unspecified, will use `{{projectNameCapitalized}}`.
    # icon:dot-circle[] icon:file-alt[]
    formulaName: App

    # A map of Homebrew dependencies.
    # The key `openjdk@${java.version}` will be added automatically if not defined.
    # icon:dot-circle[]
    dependencies:
      # key in symbol format
      # mapped as `depends_on :key1 => "value1"`
      ':key1': value1

      # plain key
      # mapped as `depends_on "key2" => "value2"`
      key2: value2

      # key in symbol format without value
      # mapped as `depends_on :key3`
      ':key3': 'null'

      # plain key without value
      # mapped as `depends_on "key4"`
      key4: 'null'

    # Additional properties used when evaluating templates.
    # icon:dot-circle[]
    extraProperties:
      # Key will be capitalized and prefixed with `brew`, i.e, `brewFoo`.
      foo: bar

    # Git author used to commit to the tap repository.
    # icon:dot-circle[]
    commitAuthor:
      # Name used when authoring commits.
      # If left undefined, will use the releaser's commit name.
      # icon:dot-circle[]
      name: jreleaser-bot

      # E-mail used when authoring commits.
      # If left undefined, will use the releaser's commit email.
      # icon:dot-circle[]
      email: pass:[jreleaser-bot@jreleaser.org]

    # Git repository to push the formula to.
    # Defaults are shown.
    # icon:dot-circle[]
    tap:

      # The owner of the tap repository.
      # Defaults to the same owner as the release repository.
      # icon:dot-circle[]
      owner: duke

      # The name of the tap repository.
      # Defaults to `homebrew-tap`.
      # icon:dot-circle[]
      name: homebrew-tap

      # Username used for authoring commits. Must have write access to the tap repository.
      # Defaults to the same username as the release repository.
      # icon:dot-circle[]
      username: duke

      # Password or OAuth token with write access to the tap repository.
      # If left unspecified, the `JRELEASER_HOMEBREW_${GIT}_TOKEN`
      # environment variable must be defined.
      # icon:dot-circle[] icon:eye-slash[]
      token: __DO_NOT_SET_HERE__
----
TOML::
+
[source,toml]
[subs="+macros"]
----
# icon:dot-circle[]
[packagers.brew]
  # Enables or disables Homebrew.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # icon:dot-circle[]
  active = "ALWAYS"

  # Directory with file templates used to prepare the Homebrew distribution
  # Defaults to `src/distribution/${distribution.name}/brew`.
  # If specified, path must exist.
  # icon:dot-circle[]
  templateDirectory = "path/to/brew/templates"

  # The class name of the generated formula.
  # If left unspecified, will use `{{projectNameCapitalized}}`.
  # icon:dot-circle[] icon:file-alt[]
  formulaName = "App"

  # A map of Homebrew dependencies.
  # The key `openjdk@${java.version}` will be added automatically if not defined.
  # icon:dot-circle[]
  # key in symbol format
  # mapped as `depends_on :key1 => "value1"`
  dependencies.":key1" = "value1"
  # plain key
  # mapped as `depends_on "key2" => "value2"`
  dependencies.key2 = "value2"
  # key in symbol format without value
  # mapped as `depends_on :key3`
  dependencies.":key3" = "null"
  # plain key without value
  # mapped as `depends_on "key4"`
  dependencies.key4 = "null"

  # Additional properties used when evaluating templates.
  # icon:dot-circle[]
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `brew`, i.e, `brewFoo`.

  # Git author used to commit to the tap repository.

  # Name used when authoring commits.
  # If left undefined, will use the releaser's commit name.
  # icon:dot-circle[]
  commitAuthor.name = "jreleaser-bot"

  # E-mail used when authoring commits.
  # If left undefined, will use the releaser's commit email.
  # icon:dot-circle[]
  commitAuthor.email = "pass:[jreleaser-bot@jreleaser.org]"

  # Git repository to push the formula to.
  # Defaults are shown.

  # The owner of the tap repository.
  # Defaults to the same owner as the release repository.
  # icon:dot-circle[]
  tap.owner = "duke"

  # The name of the tap repository.
  # Defaults to `homebrew-tap`.
  # icon:dot-circle[]
  tap.name = "homebrew-tap"

  # Username used for authoring commits. Must have write access to the tap repository.
  # Defaults to the same username as the release repository.
  # icon:dot-circle[]
  tap.username = "duke"

  # Password or OAuth token with write access to the tap repository.
  # If left unspecified, the `JRELEASER_HOMEBREW_${GIT}_TOKEN`
  # environment variable must be defined.
  # icon:dot-circle[] icon:eye-slash[]
  tap.token = "__DO_NOT_SET_HERE__"
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // icon:dot-circle[]
  "packagers": {
    // icon:dot-circle[]
    "brew": {
      // Enables or disables Homebrew.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      "active": "ALWAYS",

      // Directory with file templates used to prepare the Homebrew distribution
      // Defaults to `src/distribution/${distribution.name}/brew`.
      // If specified, path must exist.
      // icon:dot-circle[]
      "templateDirectory": "path/to/brew/templates",

      // The class name of the generated formula.
      // If left unspecified, will use `{{projectNameCapitalized}}`.
      // icon:dot-circle[] icon:file-alt[]
      "formulaName": "App",

      // A map of Homebrew dependencies.
      // The key `openjdk@${java.version}` will be added automatically if not defined.
      // icon:dot-circle[]
      "dependencies": {
        // key in symbol format
        // mapped as `depends_on :key1 => "value1"`
        ":key1": "value1",

        // plain key
        // mapped as `depends_on "key2" => "value2"`
        "key2": "value2",

        // key in symbol format without value
        // mapped as `depends_on :key3`
        ":key3": "null",

        // plain key without value
        // mapped as `depends_on "key4"`
        "key4": "null"
      },

      // Additional properties used when evaluating templates.
      // icon:dot-circle[]
      "extraProperties": {
        // Key will be capitalized and prefixed with `brew`, i.e, `brewFoo`.
        "foo": "bar"
      },

      // Git author used to commit to the tap repository.
      // icon:dot-circle[]
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaser-bot`.
        // icon:dot-circle[]
        "name": "jreleaser-bot",

        // E-mail used when authoring commits.
        // Defaults to `pass:[jreleaser-bot@jreleaser.org]`.
        // icon:dot-circle[]
        "email": "pass:[jreleaser-bot@jreleaser.org]"
      },

      // Git repository to push the formula to.
      // Defaults are shown.
      // icon:dot-circle[]
      "tap": {

        // The owner of the tap repository.
        // Defaults to the same owner as the release repository.
        // icon:dot-circle[]
        "owner": "duke",

        // The name of the tap repository.
        // Defaults to `homebrew-tap`.
        // icon:dot-circle[]
        "name": "homebrew-tap",

        // Username used for authoring commits. Must have write access to the tap repository.
        // Defaults to the same username as the release repository.
        // icon:dot-circle[]
        "username": "duke",

        // Password or OAuth token with write access to the tap repository.
        // If left unspecified, the `JRELEASER_HOMEBREW_${GIT}_TOKEN`
        // environment variable must be defined.
        // icon:dot-circle[] icon:eye-slash[]
        "token": "__DO_NOT_SET_HERE__"
      }
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    icon:dot-circle[]
  -->
  <packagers>
    <!--
      icon:dot-circle[]
    -->
    <brew>
      <!--
        Enables or disables Homebrew.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        icon:dot-circle[]
      -->
      <active>ALWAYS</active>

      <!--
        Directory with file templates used to prepare the Homebrew distribution
        Defaults to `src/distribution/${distribution.name}/brew`.
        If specified, path must exist.
        icon:dot-circle[]
      -->
      <templateDirectory>>path/to/brew/templates</templateDirectory>

      <!--
        The class name of the generated formula.
        If left unspecified, will use `{{projectNameCapitalized}}`.
        icon:dot-circle[] icon:file-alt[]
      -->
      <formulaName>App</formulaName>

      <!--
        A map of Homebrew dependencies.
        The key `openjdk@${java.version}` will be added automatically if not defined.
        icon:dot-circle[]
      -->
      <dependencies>
        <!--
          key in symbol format
          mapped as `depends_on :key1 => "value1"`
        -->
        <dependency>
          <key>:key1</key>
          <value>value1</value>
        </dependency>

        <!--
          plain key
          mapped as `depends_on "key2" => "value2"`
        -->
        <dependency>
          <key>key2</key>
          <value>value2</value>
        </dependency>

        <!--
          key in symbol format without value
          mapped as `depends_on :key3`
        -->
        <dependency>
          <key>:key3</key>
        </dependency>

        <!--
          plain key without value
          mapped as `depends_on "key4"`
        -->
        <dependency>
          <key>key4</key>
        </dependency>
      </dependencies>

      <!--
        Additional properties used when evaluating templates.
        icon:dot-circle[]
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `brew`, i.e, `brewFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>

      <!--
        Git author used to commit to the repository.
        icon:dot-circle[]
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaser-bot`.
          icon:dot-circle[]
        -->
        <name>jreleaser-bot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `pass:[jreleaser-bot@jreleaser.org]`.
          icon:dot-circle[]
        -->
        <email>pass:[jreleaser-bot@jreleaser.org]</email>
      </commitAuthor>

      <!--
        Git repository to push the formula to.
        Defaults are shown.
        icon:dot-circle[]
      -->
      <tap>

        <!--
          The owner of the tap repository.
          Defaults to the same owner as the release repository.
          icon:dot-circle[]
        -->
        <owner>duke</owner>

        <!--
          The name of the tap repository.
          Defaults to `homebrew-tap`.
          icon:dot-circle[]
        -->
        <name>homebrew-tap</name>

        <!--
          Username used for authoring commits. Must have write access to the tap repository.
          Defaults to the same username as the release repository.
          icon:dot-circle[]
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the tap repository.
          If left unspecified, the `JRELEASER_HOMEBREW_${GIT}_TOKEN`
          environment variable must be defined.
          icon:dot-circle[] icon:eye-slash[]
        -->
        <token>__DO_NOT_SET_HERE__</token>
      </tap>
    </brew>
  </packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // icon:dot-circle[]
  packagers {
    // icon:dot-circle[]
    brew {
      // Enables or disables Homebrew.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      active = 'ALWAYS'

      // Directory with file templates used to prepare the Homebrew distribution
      // Defaults to `src/distribution/${distribution.name}/brew`.
      // If specified, path must exist.
      // icon:dot-circle[]
      templateDirectory = 'path/to/brew/templates'

      // The class name of the generated formula.
      // If left unspecified, will use `{{projectNameCapitalized}}`.
      // icon:dot-circle[] icon:file-alt[]
      formulaName = 'App'

      // A map of Homebrew dependencies.
      // The key `openjdk@${java.version}` will be added automatically if not defined.
      // icon:dot-circle[]
      dependencies {
        // key in symbol format
        // mapped as `depends_on :key1 => "value1"`
        addDepencency(':key1', 'value1')

        // plain key
        // mapped as `depends_on "key2" => "value2"`
        addDepencency('key2', 'value2')

        // key in symbol format without value
        // mapped as `depends_on :key3`
        addDependency(':key3')

        // plain key without value
        // mapped as `depends_on "key4"`
        addDependency('key4')
      }

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `brew`, i.e, `brewFoo`.
      // icon:dot-circle[]
      extraProperties.put('foo', 'bar')

      // Git author used to commit to the tap repository.
      // icon:dot-circle[]
      commitAuthor {
        // Name used when authoring commits.
        // If left undefined, will use the releaser's commit name.
        // icon:dot-circle[]
        name = 'jreleaser-bot'

        // E-mail used when authoring commits.
        // If left undefined, will use the releaser's commit email.
        // icon:dot-circle[]
        email = 'pass:[jreleaser-bot@jreleaser.org]'
      }  

      // Git repository to push the formula to.
      // Defaults are shown.
      // icon:dot-circle[]
      tap {

        // The owner of the tap repository.
        // Defaults to the same owner as the release repository.
        // icon:dot-circle[]
        owner = 'duke'

        // The name of the tap repository.
        // Defaults to `homebrew-tap`.
        // icon:dot-circle[]
        name = 'homebrew-tap'

        // Username used for authoring commits. Must have write access to the tap repository.
        // Defaults to the same username as the release repository.
        // icon:dot-circle[]
        username = 'duke'

        // Password or OAuth token with write access to the tap repository.
        // If left unspecified, the `JRELEASER_HOMEBREW_${GIT}_TOKEN`
        // environment variable must be defined.
        // icon:dot-circle[] icon:eye-slash[]
        token = '__DO_NOT_SET_HERE__'
      }
    }
  }      
}
----
====

NOTE: The tap token environment variable must match with the chosen xref:release/index.adoc[] service, that is, it must
be one of [`JRELEASER_HOMEBREW_GITHUB_TOKEN`, `JRELEASER_HOMEBREW_GITLAB_TOKEN`, `JRELEASER_HOMEBREW_GITEA_TOKEN`].

IMPORTANT: Formula names must be unique!

Assuming that the current version is `1.2.3`, and a distribution named `app`, the above configuration will generate
a `app.rb` formula in the `duke/homebrew-tap` repository:

[source,ruby]
----
class App < Formula
  desc "Sample app"
  homepage "https://acme.com/app"
  version "1.2.3"
  url "https://github.com/duke/app/releases/download/v1.2.3/app-1.2.3.zip"
  sha256 "812121a64bbd3f49286f7b0be3c9209068f71fcf9541f313708979602e8de466"
  license "Apache-2.0"

  bottle :unneeded

  depends_on "openjdk@8"

  def install
    libexec.install Dir["*"]
    bin.install_symlink "#{libexec}/bin/app"
  end

  test do
    output = shell_output("#{bin}/app --version")
    assert_match "1.2.3", output
  end
end
----

NOTE: JReleaser does not generate a valid homebrew-core formula. The generated formulas are meant to be published as
link:https://docs.brew.sh/Taps.html[homebrew taps], and in their current form will not be accepted in any of the official
homebrew repositories.