Article

Processes file templates suitable for publication as articles, blogs, pages, etc.

Processed files may be uploaded to a Git repository of your choosing.

Configuration

Legend:

  • required

  • optional

  • may use environment variable

  • accepts Name Templates

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

announce:
  # 
  article:

    # Enable or disable this announcer.
    # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
    # Defaults to `NEVER`.
    #  
    active: ALWAYS

    # Directory with file templates.
    # Defaults to `src/jreleaser/templates/article`.
    # Path must exist.
    # 
    templateDirectory: src/jreleaser/templates/article

    # Defines a list of files.
    # Each entry must define a path: field.
    # The path may be relative to templateDirectory or absolute.
    #  
    files:
      - path: path/to/some/file.md

    # Git author used to commit to the repository.
    # 
    commitAuthor:
      # Name used when authoring commits.
      # Defaults to `jreleaserbot`.
      # 
      name: jreleaserbot

      # E-mail used when authoring commits.
      # Defaults to `jreleaser@kordamp.org`.
      # 
      email: jreleaser@kordamp.org

    # Git repository to push the templates to.
    # Defaults are shown.
    # 
    repository:
      # Enables or disables the repository.
      # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      # Defaults to `RELEASE`.
      # 
      active: ALWAYS
      # The owner of the repository.
      # Defaults to the same owner as the release repository.
      # 
      owner: duke

      # The name of the repository.
      # Defaults to `duke-docs`.
      # 
      name: duke-docs

      # The tag associated with the templates.
      # If left unspecified, will use `{{tagName}}`.
      #  
      tagName: '{{distributionName}}-{{tagName}}'

      # The target branch to pull from.
      # Defaults to the branch pointed by HEAD.
      #  
      branch: HEAD

      # The target branch to push to.
      # Defaults to the branch pointed by `#{branch}`.
      #   
      branchPush: '{{projectName}}-{{tagName}}'

      # Username used for authoring commits.
      # Must have write access to the repository.
      # Defaults to the same username as the release repository.
      #  
      username: duke

      # Password or OAuth token with write access to the repository.
      #  
      token: __USE_ENVIRONMENT_VARIABLE__

      # Message when committing to the repository.
      # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
      #  
      commitMessage: '{{distributionName}} {{tagName}}'

      # Additional properties used when evaluating templates.
      #  
      extraProperties:
        # Key will be capitalized and prefixed with `repository`, i.e, `repositoryFoo`.
        foo: bar

    # Additional properties used when evaluating templates.
    #  
    extraProperties:
      # Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
      foo: bar
# 
[announce.article]

  # Enable or disable this announcer.
  # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `NEVER`.
  #  
  active = "ALWAYS"

  # Directory with file templates.
  # Defaults to `src/jreleaser/templates/article`.
  # Path must exist.
  # 
  templateDirectory = "src/jreleaser/templates/article"

  # Defines a list of files.
  # Each entry must define a path: field.
  # The path may be relative to templateDirectory or absolute.
  #  
  files = [
    { path = "path/to/some/file.md" }
  ]

  # Git author used to commit to the repository.

  # Name used when authoring commits.
  # Defaults to `jreleaserbot`.
  # 
  commitAuthor.name = "jreleaserbot"

  # E-mail used when authoring commits.
  # Defaults to `jreleaser@kordamp.org`.
  # 
  commitAuthor.email = "jreleaser@kordamp.org"

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

  # Enables or disables the repository.
  # Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
  # Defaults to `RELEASE`.
  # 
  repository.active = "ALWAYS"
  # The owner of the repository.
  # Defaults to the same owner as the release repository.
  # 
  repository.owner = "duke"

  # The name of the repository.
  # Defaults to `duke-docs`.
  # 
  repository.name = "duke-docs"

  # The tag associated with the templates.
  # If left unspecified, will use `{{tagName}}`.
  #  
  repository.tagName = "{{distributionName}}-{{tagName}}"

  # The target branch to pull from.
  # Defaults to the branch pointed by HEAD.
  #  
  repository.branch = "HEAD"

  # The target branch to push to.
  # Defaults to the branch pointed by `#{branch}`.
  #    
  repository.branchPush = "{{projectName}}-{{tagName}}"

  # Username used for authoring commits.
  # Must have write access to the repository.
  # Defaults to the same username as the release repository.
  #  
  repository.username = "duke"

  # Password or OAuth token with write access to the repository.
  #  
  repository.token = "__USE_ENVIRONMENT_VARIABLE__"

  # Message when committing to the repository.
  # If left unspecified, `{{distributionName}} {{tagName}}` will be used.
  #  
  repository.commitMessage = "{{distributionName}} {{tagName}}"

  # Additional properties used when evaluating templates.
  #  
  repository.extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `repository`, i.e, `repositoryFoo`.

  # Additional properties used when evaluating templates.
  #  
  extraProperties.foo = "bar"
  # Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
{
  "announce": {
    // 
    "article": {

      // Enable or disable this announcer.
      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      //  
      "active": "ALWAYS",

      // Directory with file templates.
      // Defaults to `src/jreleaser/templates/article`.
      // Path must exist.
      // 
      "templateDirectory": "src/jreleaser/templates/article",

      // Defines a list of files.
      // Each entry must define a path: field.
      // The path may be relative to templateDirectory or absolute.
      //  
      "files": [
        {
          "path": "path/to/some/file.md"
        }
      ]

      // Git author used to commit to the repository.
      // 
      "commitAuthor": {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        "name": "jreleaserbot",

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        "email": "jreleaser@kordamp.org"
      },

      // Git repository to push the templates to.
      // Defaults are shown.
      // 
      "repository": {
        // Enables or disables the repository.
        // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `RELEASE`.
        // 
        "active": "ALWAYS",
        // The owner of the repository.
        // Defaults to the same owner as the release repository.
        // 
        "owner": "duke",

        // The name of the repository.
        // Defaults to `duke-docs`.
        // 
        "name": "duke-docs",

        // The tag associated with the templates.
        // If left unspecified, will use `{{tagName}}`.
        //  
        "tagName": "{{distributionName}}-{{tagName}}",

        // The target branch to pull from.
        // Defaults to the branch pointed by HEAD.
        //  
        "branch": "HEAD",

        // The target branch to push to.
        // Defaults to the branch pointed by `#{branch}`.
        //   
        "branchPush": "{{projectName}}-{{tagName}}",

        // Username used for authoring commits.
        // Must have write access to the repository.
        // Defaults to the same username as the release repository.
        //  
        "username": "duke",

        // Password or OAuth token with write access to the repository.
        //  
        "token": "__USE_ENVIRONMENT_VARIABLE__",

        // Message when committing to the repository.
        // If left unspecified, `{{distributionName}} {{tagName}}` will be used.
        //  
        "commitMessage": "{{distributionName}} {{tagName}}",

        // Additional properties used when evaluating templates.
        //  
        "extraProperties": {
          // Key will be capitalized and prefixed with `repository`, i.e, `repositoryFoo`.
          "foo": "bar"
        }
      },

      // Additional properties used when evaluating templates.
      //  
      "extraProperties": {
        // Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
        "foo": "bar"
      }
    }
  }
}
<jreleaser>
  <!--
    
  -->
  <announce>
    <!--
      
    -->
    <article>

      <!--
        Enable or disable this announcer.
        Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        Defaults to `NEVER`.
         
      -->
      <active>ALWAYS</active>

      <!--
        Directory with file templates.
        Defaults to `src/jreleaser/templates/article`.
        Path must exist.
        
      -->
      <templateDirectory>src/jreleaser/templates/article</templateDirectory>

      <!--
        Defines a list of files.
        Each entry must define a path: field.
        The path may be relative to templateDirectory or absolute.
         
      -->
      <files>
        <files>
          <path>path/to/some/file.md</path>
        <file>
      </files>

      <!--
        Git author used to commit to the repository.
        
      -->
      <commitAuthor>

        <!--
           Name used when authoring commits.
          Defaults to `jreleaserbot`.
          
        -->
        <name>jreleaserbot</name>

        <!--
          E-mail used when authoring commits.
          Defaults to `jreleaser@kordamp.org`.
          
        -->
        <email>jreleaser@kordamp.org</email>
      </commitAuthor>

      <!--
        Git repository to push the templates to.
        Defaults are shown.
        
      -->
      <repository>
        <!--
          Enables or disables the repository.
          Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
          Defaults to `RELEASE`.
          
        -->
        <active>ALWAYS</active>
        <!--
          The owner of the repository.
          Defaults to the same owner as the release repository.
          
        -->
        <owner>duke</owner>

        <!--
          The name of the repository.
          Defaults to `duke-docs`.
          
        -->
        <name>duke-docs</name>

        <!--
          The tag associated with the templates.
          If left unspecified, will use `{{tagName}}`.
           
        -->
        <tagName>{{distributionName}}-{{tagName}}</tagName>

        <!--
          The target branch to pull from.
          Defaults to the branch pointed by HEAD.
           
        -->
        <branch>HEAD</branch>

        <!--
          The target branch to push to.
          Defaults to the branch pointed by `#{branch}`.
            
        -->
        <branchPush>{{projectName}}-{{tagName}}</branchPush>

        <!--
          Username used for authoring commits.
          Must have write access to the repository.
          Defaults to the same username as the release repository.
           
        -->
        <username>duke</username>

        <!--
          Password or OAuth token with write access to the repository.
           
        -->
        <token>__USE_ENVIRONMENT_VARIABLE__</token>

        <!--
          Message when committing to the repository.
          If left unspecified, `{{distributionName}} {{tagName}}` will be used.
           
        -->
        <commitMessage>{{distributionName}} {{tagName}}</commitMessage>

        <!--
          Additional properties used when evaluating templates.
           
        -->
        <extraProperties>
          <!--
            Key will be capitalized and prefixed with `repository`, i.e, `repositoryFoo`.
          -->
          <foo>bar</foo>
        </extraProperties>
      </repository>

      <!--
        Additional properties used when evaluating templates.
         
      -->
      <extraProperties>
        <!--
          Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
        -->
        <foo>bar</foo>
      </extraProperties>
    </article>
  </announce>
</jreleaser>
jreleaser {
  announce {
    // 
    article {

      // Enable or disable this announcer.
      // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
      // Defaults to `NEVER`.
      //  
      active = 'ALWAYS'

      // Directory with file templates.
      // Defaults to `src/jreleaser/templates/article`.
      // Path must exist.
      // 
      templateDirectory = 'src/jreleaser/templates/article'

      // Defines a list of files.
      // Each entry must define a path: field.
      // The path may be relative to templateDirectory or absolute.
      //  
      file {
        path = 'path/to/some/file.md'
      }

      // Git author used to commit to the repository.
      // 
      commitAuthor {
        // Name used when authoring commits.
        // Defaults to `jreleaserbot`.
        // 
        name = 'jreleaserbot'

        // E-mail used when authoring commits.
        // Defaults to `jreleaser@kordamp.org`.
        // 
        email = 'jreleaser@kordamp.org'
      }

      // Git repository to push the templates to.
      // Defaults are shown.
      // 
      repository {
        // Enables or disables the repository.
        // Supported values are [`NEVER`, `ALWAYS`, `RELEASE`, `SNAPSHOT`].
        // Defaults to `RELEASE`.
        // 
        active = 'ALWAYS'
        // The owner of the repository.
        // Defaults to the same owner as the release repository.
        // 
        repoOwner = 'duke'

        // The name of the repository.
        // Defaults to `duke-docs`.
        // 
        name = 'duke-docs'

        // The tag associated with the templates.
        // If left unspecified, will use `{{tagName}}`.
        //  
        tagName = '{{distributionName}}-{{tagName}}'

        // The target branch to pull from.
        // Defaults to the branch pointed by HEAD.
        //  
        branch = 'HEAD'

        // The target branch to push to.
        // Defaults to the branch pointed by `#{branch}`.
        //   
        branchPush = '{{projectName}}-{{tagName}}'

        // Username used for authoring commits.
        // Must have write access to the repository.
        // Defaults to the same username as the release repository.
        //  
        username = 'duke'

        // Password or OAuth token with write access to the repository.
        //  
        token = '__USE_ENVIRONMENT_VARIABLE__'

        // Message when committing to the repository.
        // If left unspecified, `{{distributionName}} {{tagName}}` will be used.
        //  
        commitMessage = '{{distributionName}} {{tagName}}'

        // Additional properties used when evaluating templates.
        // Key will be capitalized and prefixed with `repository`, i.e, `repositoryFoo`.
        //  
        extraProperties.put('foo', 'bar')
      }

      // Additional properties used when evaluating templates.
      // Key will be capitalized and prefixed with `article`, i.e, `articleFoo`.
      //  
      extraProperties.put('foo', 'bar')
    }
  }
}

Environment

When not explicitly set, the value of the following properties may be resolved from an environment variable or a system property as shown in the table. The system property takes precedence over the environment variable.

System Property Environment Variable

active

jreleaser.announce.article.active

JRELEASER_ANNOUNCE_ARTICLE_ACTIVE

repository.active

jreleaser.announce.article.repository.active

JRELEASER_ANNOUNCE_ARTICLE_REPOSITORY_ACTIVE

repository.username

jreleaser.announce.article.repository.username
jreleaser.article.github.username
jreleaser.article.gitlab.username
jreleaser.article.gitea.username
jreleaser.article.codeberg.username
jreleaser.github.username
jreleaser.gitlab.username
jreleaser.gitea.username
jreleaser.codeberg.username

JRELEASER_ANNOUNCE_ARTICLE_REPOSITORY_USERNAME
JRELEASER_ARTICLE_GITHUB_USERNAME
JRELEASER_ARTICLE_GITLAB_USERNAME
JRELEASER_ARTICLE_GITEA_USERNAME
JRELEASER_ARTICLE_CODEBERG_USERNAME
JRELEASER_GITHUB_USERNAME
JRELEASER_GITLAB_USERNAME
JRELEASER_GITEA_USERNAME
JRELEASER_CODEBERG_USERNAME

repository.token

jreleaser.announce.article.repository.token
jreleaser.article.github.token
jreleaser.article.gitlab.token
jreleaser.article.gitea.token
jreleaser.article.codeberg.token
jreleaser.github.token
jreleaser.gitlab.token
jreleaser.gitea.token
jreleaser.codeberg.token

JRELEASER_ANNOUNCE_ARTICLE_REPOSITORY_TOKEN
JRELEASER_ARTICLE_GITHUB_TOKEN
JRELEASER_ARTICLE_GITLAB_TOKEN
JRELEASER_ARTICLE_GITEA_TOKEN
JRELEASER_ARTICLE_CODEBERG_TOKEN
JRELEASER_GITHUB_TOKEN
JRELEASER_GITLAB_TOKEN
JRELEASER_GITEA_TOKEN
JRELEASER_CODEBERG_TOKEN

repository.branch

jreleaser.announce.article.repository.branch
jreleaser.article.github.branch
jreleaser.article.gitlab.branch
jreleaser.article.gitea.branch
jreleaser.article.codeberg.branch
jreleaser.github.branch
jreleaser.gitlab.branch
jreleaser.gitea.branch
jreleaser.codeberg.branch

JRELEASER_ANNOUNCE_ARTICLE_REPOSITORY_BRANCH
JRELEASER_ARTICLE_GITHUB_BRANCH
JRELEASER_ARTICLE_GITLAB_BRANCH
JRELEASER_ARTICLE_GITEA_BRANCH
JRELEASER_ARTICLE_CODEBERG_BRANCH
JRELEASER_GITHUB_BRANCH
JRELEASER_GITLAB_BRANCH
JRELEASER_GITEA_BRANCH
JRELEASER_CODEBERG_BRANCH

repository.branchPush

jreleaser.announce.article.repository.branch.push
jreleaser.article.github.branch.push
jreleaser.article.gitlab.branch.push
jreleaser.article.gitea.branch.push
jreleaser.article.codeberg.branch.push
jreleaser.github.branch.push
jreleaser.gitlab.branch.push
jreleaser.gitea.branch.push
jreleaser.codeberg.branch.push

JRELEASER_ANNOUNCE_ARTICLE_REPOSITORY_BRANCH_PUSH
JRELEASER_ARTICLE_GITHUB_BRANCH_PUSH
JRELEASER_ARTICLE_GITLAB_BRANCH_PUSH
JRELEASER_ARTICLE_GITEA_BRANCH_PUSH
JRELEASER_ARTICLE_CODEBERG_BRANCH_PUSH
JRELEASER_GITHUB_BRANCH_PUSH
JRELEASER_GITLAB_BRANCH_PUSH
JRELEASER_GITEA_BRANCH_PUSH
JRELEASER_CODEBERG_BRANCH_PUSH

Repository

The repository section allows setting extra properties that may be used to provide additional hints when interacting with the git repository that holds article sources.

GitLab

Define a projectIdentifier property to directly locate the project associated with the repository, such as

  • YAML

  • TOML

  • JSON

  • Maven

  • Gradle

announce:
  article:
    repository:
      extraProperties:
        projectIdentifier: 12345678
[announce.article]
  repository.extraProperties.projectIdentifier = "12345678"
{
  "announce": {
    "article": {
      "repository": {
        "extraProperties": {
          "projectIdentifier": "12345678"
        }
      }
    }
  }
}
<jreleaser>
  <announce>
    <article>
      <repository>
        <extraProperties>
          <projectIdentifier>12345678</projectIdentifier>
        </extraProperties>
      </repository>
    </article>
  </announce>
</jreleaser>
jreleaser {
  announce {
    article {
      repository {
        extraProperties.put("projectIdentifier", "12345678")
      }
    }
  }
}

Example

Given a project configured as

jreleaser.yml
project:
  version: 1.2.3
  description: Sample application
  longDescription: Sample application
  authors:
    - Duke
  license: Apache-2.0
  links:
    homepage: https://github.com/duke/app
  java:
    groupId: com.acme
    version: 8
    mainClass: com.acme.Main
  inceptionYear: 2021

releaser:
  github:
    owner: duke

distributions:
  app:
    artifacts:
      - path: 'target/distributions/{{distributionName}}/{{distributionName}}-{{projectVersion}}.zip'

announce:
  article:
    active: ALWAYS
    repository:
      name: docs
    files:
      - path: 'post.adoc'
        transform: '_posts/{{#f_now}}YYYY-MM-dd{{/f_now}}/{{projectName}}-{{#f_dash}}{{projectVersion}}{{/f_dash}}-released.adoc'

And file named post.adoc located at src/jreleaser/templates/article

---
layout: post
title: '{{projectNameCapitalized}} {{projectEffectiveVersion}} released'
date: {{#f_now}}YYYY-MM-dd{{/f_now}}
tags: release
synopsis: {{projectEffectiveVersion}} is the latest release.
author: duke
---

We just released {{projectNameCapitalized}} {{projectEffectiveVersion}} with a new round of bugfixes and documentation improvements.

== Full changelog

You can get {{releaseNotesUrl}}[the full changelog of {{projectEffectiveVersion}} on GitHub].

Generates the following file structure

out
└── jreleaser
    ├── output.properties
    ├── prepare
    │   └── article
    │       └── _posts
    │           └── 2021-07-26
    │               └── app-1-0-0-released.adoc
    ├── release
    │   └── CHANGELOG.md
    └── trace.log

The contents of the parsed template look like this

---
layout: post
title: 'App 1.2.3 released'
date: 2021-07-26
tags: release
synopsis: 1.0.0 is the latest release.
author: duke
---

We just released App 1.2.3 with a new round of bugfixes and documentation improvements.

== Full changelog

You can get https://github.com/duke/app/releases/tag/v1.2.3[the full changelog of 1.2.3 on GitHub].

This file will be uploaded to the https://github.com/duke/docs repository as _posts/2021-07-26/app-1-0-0-released.adoc.