= Chocolatey

Publishes packages to link:https://chocolatey.org[].

NOTE: At the moment, only artifacts with `.zip` extension may be packaged with Chocolatey.

WARNING: Local publication of packages is currently not supported. Please set `remoteBuild` to `true` and trigger a
build on CI. Local publication will be added at a later release.

WARNING: Snapshots are *not* supported.

include::partial$legend.adoc[]

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

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

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

    # The username that can publish Chocolatey packages.
    # If left unspecified, the release owner will be used.
    # icon:exclamation-triangle[]
    username: duke

    # Whether to build the package on a remote server or locally.
    # Defaults to `false`.
    # icon:dot-circle[]
    remoteBuild: false

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

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

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

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

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

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

      # Password or OAuth token with write access to the bucket repository.
      # If left unspecified, the `JRELEASER_CHOCOLATEY_${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.chocolatey]
  # Enables or disables Chocolatey.
  # Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  # icon:dot-circle[]
  active = "ALWAYS"

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

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

  # The username that can publish Chocolatey packages.
  # If left unspecified, the release owner will be used.
  # icon:exclamation-triangle[]
  username = "duke"

  # Whether to build the package on a remote server or locally.
  # Defaults to `false`.
  # icon:dot-circle[]
  remoteBuild = false

  # Git author used to commit to the bucket repository.

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

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

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

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

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

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

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

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

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

      // The username that can publish Chocolatey packages.
      // If left unspecified, the release owner will be used.
      // icon:exclamation-triangle[]
      "username": "duke",

      // Whether to build the package on a remote server or locally.
      // Defaults to `false`.
      // icon:dot-circle[]
      "remoteBuild": false,

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

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

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

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

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

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

        // Password or OAuth token with write access to the bucket repository.
        // If left unspecified, the `JRELEASER_CHOCOLATEY_${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[]
    -->
    <chocolatey>
      <!--
        Enables or disables Chocolatey.
        Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
        icon:dot-circle[]
      -->
      <active>ALWAYS</active>

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

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

      <!--
        The username that can publish Chocolatey packages.
        If left unspecified, the release owner will be used.
        icon:exclamation-triangle[]
      -->
      <username>duke</username>

      <!--
        Whether to build the package on a remote server or locally.
        Defaults to `false`.
        icon:dot-circle[]
      -->
      <remoteBuild>false</remoteBuild>

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

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

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

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

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

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

        <!--
          Username used for authoring commits. Must have write access to the bucket 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 bucket repository.
          If left unspecified, the `JRELEASER_CHOCOLATEY_${GIT}_TOKEN`
          environment variable must be defined.
          icon:dot-circle[] icon:eye-slash[]
        -->
        <token>__DO_NOT_SET_HERE__</token>
      </bucket>
    </chocolatey>
  </packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // icon:dot-circle[]
  packagers {
    // icon:dot-circle[]
    chocolatey {
      // Enables or disables Chocolatey.
      // Valid values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      // icon:dot-circle[]
      active = 'ALWAYS'

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

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

      // The username that can publish Chocolatey packages.
      // If left unspecified, the release owner will be used.
      // icon:exclamation-triangle[]
      username = 'duke'

      // Whether to build the package on a remote server or locally.
      // Defaults to `false`.
      // icon:dot-circle[]
      remoteBuild = false

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

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

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

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

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

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

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

Template files may be initialized using the `template` command.

NOTE: The bucket token environment variable must match with the chosen xref:release/index.adoc[] service, that is, it must
be one of [`JRELEASER_CHOCOLATEY_GITHUB_TOKEN`, `JRELEASER_CHOCOLATEY_GITLAB_TOKEN`, `JRELEASER_CHOCOLATEY_GITEA_TOKEN`].

Assuming that the current version is `1.2.3`, and a distribution named `app`, the above configuration will generate
the following files in `out/jreleaser/app/prepare`, which will be published to `duke/chocolatey-bucket/app`

[source,xml]
[subs="verbatim"]
.app.nuspec
----
<?xml version="1.0" encoding="utf-8"?>
<!-- Do not remove this test for UTF-8: if “Ω” doesn’t appear as greek uppercase omega letter enclosed in quotation marks, you should use an editor that supports UTF-8, not this one. -->
<package xmlns="http://schemas.microsoft.com/packaging/2015/06/nuspec.xsd">
  <metadata>
    <!-- required -->
    <id>app</id>
    <version>1.2.3</version>
    <authors>Duke</authors>
    <description>Sample app</description>
    <!-- optional -->
    <title>app</title>
    <projectUrl>https://acme.com/app</projectUrl>
    <license type="expression">Apache-2.0</license>
    <requireLicenseAcceptance>false</requireLicenseAcceptance>
    <tags></tags>
    <summary>Sample app</summary>
    <releaseNotes>https://github.com/duke/app/releases/tag/v1.2.3</releaseNotes>
  </metadata>
  <files>
    <file src="tools\**" target="tools" />
  </files>
</package>
----

[source]
.tools/chocolateyinstall.ps1
----
$tools = Split-Path $MyInvocation.MyCommand.Definition
$package = Split-Path $tools
$app_home = Join-Path $package 'app-1.2.3'
$app_bat = Join-Path $app_home 'bin/app.cmd'

Install-ChocolateyZipPackage `
    -PackageName 'app' `
    -Url 'https://github.com/duke/app/releases/download/v1.2.3/app-1.2.3.zip' `
    -Checksum '812121a64bbd3f49286f7b0be3c9209068f71fcf9541f313708979602e8de466' `
    -ChecksumType 'sha256' `
    -UnzipLocation $package

Install-BinFile -Name 'app' -Path $app_bat
----

[source]
.tools/chocolateyuninstall.ps1
----
$tools = Split-Path $MyInvocation.MyCommand.Definition
$package = Split-Path $tools
$app_home = Join-Path $package 'app-1.2.3'
$app_bat = Join-Path $app_home 'bin/app.cmd'

Uninstall-BinFile -Name 'app' -Path $app_bat
----

