= GitHub Actions

JReleaser can be used as a link:https://github.com/features/actions[GitHub Action] with the official
link:https://github.com/jreleaser/release-action[JReleaser Action].

image::ROOT:jreleaser-github-action.png[]

You can create a workflow for pushing your releases by putting YAML configuration to `.github/workflows/release.yml`.

NOTE: If you're already building with either Maven or Gradle then you might use the
xref:tools:jreleaser-maven.adoc[] or the xref:tools:jreleaser-gradle.adoc[] instead.

:project-owner: jreleaser
:project-name:  release-action

image:https://github.com/{project-owner}/{project-name}/workflows/Test/badge.svg["Build Status", link="https://github.com/{project-owner}/{project-name}/actions"]
image:https://img.shields.io/github/v/release/{project-owner}/{project-name}["GitHub release", link="https://github.com/jreleaser/release-action/releases"]

== Usage

=== Workflow

[source,yaml]
----
name: release

on:
  workflow_dispatch:

jobs:
  release:
    name: Release
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v2
        with:
          fetch-depth: 0

      # Configure build steps as you'd normally do

      - name: Setup Java
        uses: actions/setup-java@v1
        with:
          java-version: 1.8
          server-id: central
          server-username: MAVEN_USERNAME
          server-password: MAVEN_CENTRAL_TOKEN
          gpg-private-key: ${{ secrets.GPG_PRIVATE_KEY }}
          gpg-passphrase: MAVEN_GPG_PASSPHRASE

      # Post JARs to Maven Central

      - name: Release to Maven Central
        env:
          MAVEN_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
          MAVEN_CENTRAL_TOKEN: ${{ secrets.SONATYPE_PASSWORD }}
          MAVEN_GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }}
        run: |
          export GPG_TTY=$(tty)
          git config user.name "${{ github.event.head_commit.committer.name }}"
          git config user.email "${{ github.event.head_commit.committer.email }}"
          mvn -B --file pom.xml release:prepare release:perform

      # IMPORTANT!

      - name: Setup Java for JReleaser
        uses: actions/setup-java@v1
        with:
          java-version: 11

      # Create a release

      - name: Run JReleaser
        uses: jreleaser/release-action@v1
        env:
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
----

WARNING: Note the `fetch-depth: 0` option on the `Checkout` workflow step. It is required for JReleaser to work properly.
Without that, JReleaser might fail or behave incorrectly.

The last step executes a `full-release` with the default `jreleaser.yml` configuration that's expected
to be located at the root of the repository.

IMPORTANT: This action requires Java 11+ to download and execute JReleaser. If your project already builds with Java 11+
then you can skip the second "setup" step.

== Customizing

== Inputs

Following inputs can be used as `step.with` keys

[%header,cols="<2,<,<2,<3",width="100%"]
|===
| Name              | Type   | Default                 | Description
| version           | String | latest                  | The JReleaser version to use. +
Should match any of the link:https://github.com/jreleaser/jreleaser/releases[published releases].
| arguments         | String | full-release            | The JReleaser command to run.
| working-directory | String | ${{ github.workspace }} | The directory to change into. +
Defaults to the directory the calling workflow runs in.
|===

TIP: You may use `latest` to pull the latest stable release or `early-access` to pull the latest snapshot.

Arguments may be any of those supported by the xref:tools:jreleaser-cli.adoc[CLI] tool.

== Environment Variables

Following environment variables can be used as `step.env` keys

[%header,width="100%"]
|===
| Name                   | Description
| JRELEASER_GITHUB_TOKEN | link:https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token[GITHUB_TOKEN]
as provided by `secrets`
|===

== Caution

The default `GITHUB_TOKEN` from `secrets` is link:https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#about-the-github_token-secret[limited]
to the repository that contains your workflow.

Pushing to other repositories such as Homebrew tap requires additional permissions, you must create a custom
link:https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/[Personal Access Token] with
`repo` permissions and link:https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets[add it as a secret in the repository].
If you create a secret named `GH_PAT`, the step will look like this

[source,yaml]
----
      - name: Run JReleaser
        uses: jreleaser/release-action@v1
        env:
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GH_PAT }}
----

If you'd rather have separate tokens for each additional repository and keep the original `GITHUB_TOKEN` intact then
you may apply the `GH_PAT` token as follows

[source,yaml]
----
      - name: Run JReleaser
        uses: jreleaser/release-action@v1
        env:
          JRELEASER_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          JRELEASER_HOMEBREW_GITHUB_TOKEN: ${{ secrets.GH_PAT }}
----

Additional environment variables may be needed depending on your specific setup, such as those needed for signing files
with GPG or announcing a release via Twitter. Review the xref:configuration:index.adoc[configuration] to find more about
these variables and how to set them up.

