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

= Snap

link:http://snapcraft.io[Snaps] are a new packaging format, that will let you publish your project directly to the
Ubuntu store. From there it will be installable in all the link:https://snapcraft.io/docs/core/install[supported Linux distros],
with automatic and transactional updates.

You can read more about it in the link:https://snapcraft.io/docs/[snapcraft docs].

NOTE: Only artifacts with `.tar.gz`, `.tar`, or `.jar` extension may be packaged with Snapcraft.

WARNING: Snapshots are *not* supported.

IMPORTANT: Building local snaps requires `snapcraft` to be pre installed. JReleaser will not install it nor its
dependencies.

include::partial$legend.adoc[]

[tabs]
====
YAML::
+
[source,yaml]
[subs="+macros"]
----
# icon:dot-circle[]
packagers:
  # icon:dot-circle[]
  snap:
    # Enables or disables Snap.
    # Defaults to `false`.
    # icon:dot-circle[]
    enabled: true

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

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

    # Git author used to commit to the snap 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[]
    snap:

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

      # The name of the snap repository.
      # Defaults to `${distribution.name}-snap`.
      # icon:dot-circle[]
      name: app-snap

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

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

    # Exported snapcraft login credentials.
    # Will be sent to local snapcraft build with `snapcraft login --with ${exportedLogin}`.
    # Required if `remoteBuild` is set to `false`.
    exportedLogin:

    # Whether to build the package on a remote server or locally.
    # If set to `true` then the package must be configured to be built
    # via link:https://snapcraft.io[].
    # Review the docs at link:https://snapcraft.io/build[].
    # Defaults to `false`.
    # icon:dot-circle[]
    remoteBuild: false

    # A snap of type base to be used as the execution environment for this snap.
    # Valid values are:
    # * bare - Empty base snap;
    # * core - Ubuntu Core 16;
    # * core18 - Ubuntu Core 18.
    # Defaults to `core18`.
    # icon:dot-circle[]
    base: core18

    # A guardrail to prevent you from releasing a snap to all your users before
    # it is ready.
    # `devel` will let you release only to the `edge` and `beta` channels in the
    # store. `stable` will let you release also to the `candidate` and `stable`
    # channels. More info about channels here:
    # link:https://snapcraft.io/docs/reference/channels[].
    # Defaults to `stable`.
    # icon:dot-circle[]
    grade: stable

    # Snaps can be setup to follow three different confinement policies:
    # `strict`, `devmode` and `classic`. A strict confinement where the snap
    # can only read and write in its own namespace is recommended. Extra
    # permissions for strict snaps can be declared as `plugs` for the app, which
    # are explained later. More info about confinement here:
    # link:https://snapcraft.io/docs/reference/confinement[].
    # Defaults to `strict`.
    # icon:dot-circle[]
    confinement: strict

    # List of plug names the application is associated with.
    # When a plug is connected to one of these slots, the application
    # will be granted the permissions specified for that interface.
    # If attributes are required, or the plug name does not match the
    # interface name, more details must be declared in the `plugs` field.
    # link:https://snapcraft.io/docs/reference/interfaces[].
    # icon:dot-circle[]
    localPlugs:
      - some_plug_name

    # List of slot names the application is associated with.
    # When a plug is connected to one of these slots, the application
    # will be granted the permissions specified for that interface.
    # If attributes are required, or the slot name does not match the
    # interface name, more details must be declared in the `slots` field.
    # link:https://snapcraft.io/docs/reference/interfaces[].
    # icon:dot-circle[]
    localSlots:
      - some_slot_name

    # Allows plugs to be configured.
    # icon:dot-circle[]
    plugs:
      some_plug_name:
        key: value

    # Allows slots to be configured.
    # icon:dot-circle[]
    slots:
      some_slot_name:
        key: value
        read:
        - $HOME/.foo
        write:
        - $HOME/.foo
        - $HOME/.foobar
----
JSON::
+
[source,json]
[subs="+macros"]
----
{
  // icon:dot-circle[]
  "packagers": {
    // icon:dot-circle[]
    "snap": {
      // Enables or disables Snap.
      // Defaults to `false`.
      // icon:dot-circle[]
      "enabled": true,

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

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

      // Git author used to commit to the snap 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[]
      "snap": {

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

        // The name of the snap repository.
        // Defaults to `${distribution.name}-snap`.
        // icon:dot-circle[]
        "name": "app-snap",

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

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

      // Exported snapcraft login credentials.
      // Will be sent to local snapcraft build with `snapcraft login --with ${exportedLogin}`.
      // Required if `remoteBuild` is set to `false`.
      "exportedLogin": "path/to/login.file",

      // Whether to build the package on a remote server or locally.
      // If set to `true` then the package must be configured to be built
      // via link:https://snapcraft.io[].
      // Review the docs at link:https://snapcraft.io/build[].
      // Defaults to `false`.
      // icon:dot-circle[]
      "remoteBuild": false,

      // A snap of type base to be used as the execution environment for this snap.
      // Valid values are:
      // * bare - Empty base snap;
      // * core - Ubuntu Core 16;
      // * core18 - Ubuntu Core 18.
      // Defaults to `core18`.
      // icon:dot-circle[]
      "base": "core18",

      // A guardrail to prevent you from releasing a snap to all your users before
      // it is ready.
      // `devel` will let you release only to the `edge` and `beta` channels in the
      // store. `stable` will let you release also to the `candidate` and `stable`
      // channels. More info about channels here:
      // link:https://snapcraft.io/docs/reference/channels[].
      // Defaults to `stable`.
      // icon:dot-circle[]
      "grade": "stable",

      // Snaps can be setup to follow three different confinement policies:
      // `strict`, `devmode` and `classic`. A strict confinement where the snap
      // can only read and write in its own namespace is recommended. Extra
      // permissions for strict snaps can be declared as `plugs` for the app, which
      // are explained later. More info about confinement here:
      // link:https://snapcraft.io/docs/reference/confinement[].
      // Defaults to `strict`.
      // icon:dot-circle[]
      "confinement": "strict",

      // List of plug names the application is associated with.
      // When a plug is connected to one of these slots, the application
      // will be granted the permissions specified for that interface.
      // If attributes are required, or the plug name does not match the
      // interface name, more details must be declared in the `plugs` field.
      // link:https://snapcraft.io/docs/reference/interfaces[].
      // icon:dot-circle[]
      "localPlugs" [
        "some_plug_name"
      ],

      // List of slot names the application is associated with.
      // When a plug is connected to one of these slots, the application
      // will be granted the permissions specified for that interface.
      // If attributes are required, or the slot name does not match the
      // interface name, more details must be declared in the `slots` field.
      // link:https://snapcraft.io/docs/reference/interfaces[].
      // icon:dot-circle[]
      "localSlots" [
        "some_slot_name"
      ],

      // Allows plugs to be configured.
      // icon:dot-circle[]
      "plugs": [
        {
          "some_plug_name": {
            "key": "value"
          }
        }
      ],

      // Allows slots to be configured.
      // icon:dot-circle[]
      "slots": [
        {
          "some_slot_name": {
            "key": "value",
            "read": [
              "$HOME/.foo"
            ],
            "write": [
              "$HOME/.foo",
              "$HOME/.foobar"
            ]
          }
        }
      ]
    }
  }
}
----
Maven::
+
[source,xml]
[subs="+macros,verbatim"]
----
<jreleaser>
  <!--
    icon:dot-circle[]
  -->
  <packagers>
    <!--
      icon:dot-circle[]
    -->
    <snap>
      <!--
        Enables or disables Snap.
        Defaults to `false`.
        icon:dot-circle[]
      -->
      <enabled>true</enabled>

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

      <!--
        Additional properties used when evaluating templates.
        icon:dot-circle[]
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `snap`, i.e, `snapFoo`.
        -->
        <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[]
      -->
      <snap>

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

        <!--
          The name of the snap repository.
          Defaults to `${distribution.name}-snap`.
          icon:dot-circle[]
        -->
        <name>app-snap</name>

        <!--
          Username used for authoring commits. Must have write access to the snap 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 snap repository.
          If left unspecified, the `JRELEASER_SCNAP_${GIT}_TOKEN`
          environment variable must be defined.
          icon:dot-circle[] icon:eye-slash[]
        -->
        <token>__DO_NOT_SET_HERE__</token>
      </snap>

      <!--
        Exported snapcraft login credentials.
        Will be sent to local snapcraft build with `snapcraft login --with ${exportedLogin}`.
        Required if `remoteBuild` is set to `false`.
      -->
      <exportedLogin>path/to/login.file</exportedLogin>

      <!--
        Whether to build the package on a remote server or locally.
        If set to `true` then the package must be configured to be built
        via link:https://snapcraft.io[].
        Review the docs at link:https://snapcraft.io/build[].
        Defaults to `false`.
        icon:dot-circle[]
      -->
      <remoteBuild>false</remoteBuild>

      <!--
        A snap of type base to be used as the execution environment for this snap.
        Valid values are:
        * bare - Empty base snap;
        * core - Ubuntu Core 16;
        * core18 - Ubuntu Core 18.
        Defaults to `core18`.
        icon:dot-circle[]
      -->
      <base>core18</base>

      <!--
        A guardrail to prevent you from releasing a snap to all your users before
        it is ready.
        `devel` will let you release only to the `edge` and `beta` channels in the
        store. `stable` will let you release also to the `candidate` and `stable`
        channels. More info about channels here:
        link:https://snapcraft.io/docs/reference/channels[].
        Defaults to `stable`.
        icon:dot-circle[]
      -->
      <grade>stable</grade>

      <!--
        Snaps can be setup to follow three different confinement policies:
        `strict`, `devmode` and `classic`. A strict confinement where the snap
        can only read and write in its own namespace is recommended. Extra
        permissions for strict snaps can be declared as `plugs` for the app, which
        are explained later. More info about confinement here:
        link:https://snapcraft.io/docs/reference/confinement[].
        Defaults to `strict`.
        icon:dot-circle[]
      -->
      <confinement>strict</confinement>

      <!--
        List of plug names the application is associated with.
        When a plug is connected to one of these slots, the application
        will be granted the permissions specified for that interface.
        If attributes are required, or the plug name does not match the
        interface name, more details must be declared in the `plugs` field.
        link:https://snapcraft.io/docs/reference/interfaces[].
        icon:dot-circle[]
      -->
      <localPlugs>
        <localPlug>some_plug_name</localPlug>
      </localPlugs>

      <!--
        List of slot names the application is associated with.
        When a plug is connected to one of these slots, the application
        will be granted the permissions specified for that interface.
        If attributes are required, or the slot name does not match the
        interface name, more details must be declared in the `slots` field.
        link:https://snapcraft.io/docs/reference/interfaces[].
        icon:dot-circle[]
      -->
      <localSlots>
        <localSlot>some_slot_name</localSlot>
      </localSlots>

      <!--
        Allows plugs to be configured.
        icon:dot-circle[]
      -->
      <plugs>
        <plug>
          <name>some_plug_name</name>
          <attributes>
            <key>value</key>
          </attributes>
        </plug>
      </plugs>

      <!--
        Allows slots to be configured.
        icon:dot-circle[]
      -->
      <slots>
        <slot>
          <name>some_slot_name</name>
          <attributes>
            <key>value</key>
          </attributes>
          <reads>
            <read>$HOME/.foo</read>
          </reads>
          <writes>
            <write>$HOME/.foo</write>
            <write>$HOME/.foobar</write>
          </writes>
        </slot>
      </slots>
    </snap>
  </packagers>
</jreleaser>
----
Gradle::
+
[source,groovy]
[subs="+macros"]
----
jreleaser {
  // icon:dot-circle[]
  packagers {
    // icon:dot-circle[]
    snap {
      // Enables or disables Snap.
      // Defaults to `false`.
      // icon:dot-circle[]
      enabled = true

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

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

      // Git author used to commit to the snap 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[]
      snap {

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

        // The name of the snap repository.
        // Defaults to `${distribution.name}-snap`.
        // icon:dot-circle[]
        name = 'app-snap'

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

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

      // Exported snapcraft login credentials.
      // Will be sent to local snapcraft build with `snapcraft login --with ${exportedLogin}`.
      // Required if `remoteBuild` is set to `false`.
      exportedLogin = 'path/to/login.file'

      // Whether to build the package on a remote server or locally.
      // If set to `true` then the package must be configured to be built
      // via link:https://snapcraft.io[].
      // Review the docs at link:https://snapcraft.io/build[].
      // Defaults to `false`.
      // icon:dot-circle[]
      remoteBuild = false

      // A snap of type base to be used as the execution environment for this snap.
      // Valid values are:
      // * bare - Empty base snap;
      // * core - Ubuntu Core 16;
      // * core18 - Ubuntu Core 18.
      // Defaults to `core18`.
      // icon:dot-circle[]
      base = 'core18'

      // A guardrail to prevent you from releasing a snap to all your users before
      // it is ready.
      // `devel` will let you release only to the `edge` and `beta` channels in the
      // store. `stable` will let you release also to the `candidate` and `stable`
      // channels. More info about channels here:
      // link:https://snapcraft.io/docs/reference/channels[].
      // Defaults to `stable`.
      // icon:dot-circle[]
      grade = 'stable'

      // Snaps can be setup to follow three different confinement policies:
      // `strict`, `devmode` and `classic`. A strict confinement where the snap
      // can only read and write in its own namespace is recommended. Extra
      // permissions for strict snaps can be declared as `plugs` for the app, which
      // are explained later. More info about confinement here:
      // link:https://snapcraft.io/docs/reference/confinement[].
      // Defaults to `strict`.
      // icon:dot-circle[]
      confinement = 'strict'

      // List of plug names the application is associated with.
      // When a plug is connected to one of these slots, the application
      // will be granted the permissions specified for that interface.
      // If attributes are required, or the plug name does not match the
      // interface name, more details must be declared in the `plugs` field.
      // link:https://snapcraft.io/docs/reference/interfaces[].
      // icon:dot-circle[]
      addLocalPlug('some_plug_name')

      // List of slot names the application is associated with.
      // When a plug is connected to one of these slots, the application
      // will be granted the permissions specified for that interface.
      // If attributes are required, or the slot name does not match the
      // interface name, more details must be declared in the `slots` field.
      // link:https://snapcraft.io/docs/reference/interfaces[].
      // icon:dot-circle[]
      addLocalSlots('some_slot_name')

      // Allows plugs to be configured.
      // icon:dot-circle[]
      plugs {
        some_plug_name {
          addAttribute('key', 'value')
        }
      }

      // Allows slots to be configured.
      // icon:dot-circle[]
      slots {
        some_slot_name {
          addAttribute('key', 'value')
          addRead('$HOME/.foo')
          addWrite('$HOME/.foo')
          addWrite('$HOME/.foobar')
        }
      }
    }
  }
}
----
====

NOTE: The snap token environment variable must match with the chosen xref:release/index.adoc[] service, that is, it must
be one of [`JRELEASER_SNAP_GITHUB_TOKEN`, `JRELEASER_SNAP_GITLAB_TOKEN`, `JRELEASER_SNAP_GITEA_TOKEN`].

Assuming that the current version is `1.2.3`, and a distribution named `app`, the above configuration will generate
a `snapcraft.yaml` file `out/jreleaser/snap/prepare`, which may be published to `app-snap`

[source,yaml]
.snapcraft.yaml
----
name: app
base: core18
version: 1.2.3
license: Apache-2.0
grade: stable
type: app
confinement: strict
summary: Sample app
description: Sample app

apps:
  app:
    command: $SNAP/bin/app
    environment:
      JAVA_HOME: "$SNAP/usr/lib/jvm/java/jre/"
      PATH: "$SNAP/bin:$PATH:$SNAP/usr/lib/jvm/java/jre/bin"

parts:
  app:
    plugin: dump
    source: https://github.com/duke/app/releases/download/v1.2.3/app-1.2.3.tar.gz
    source-checksum: sha256/8e74020ca5e7d01d25c34cf1bd53adcf78c77adf7b53530ae5e0baeb841cb43e
    stage-packages:
      - openjdk-8-jdk
      - ca-certificates
      - ca-certificates-java
    organize:
      usr/lib/jvm/java-8-openjdk*: usr/lib/jvm/java
    prime:
      - -usr/lib/jvm/java/lib/security/cacerts
      - -usr/lib/jvm/java/jre/lib/security/cacerts
----