Skip to end of metadata
Go to start of metadata

Plugin Information

View Git Changelog on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Creates a changelog, or release notes, based on Git commits between 2 revisions.
Build Status

Creates a changelog, or release notes, based on Git commits between 2 revisions.

The plugin is also documented in the Jenkins wiki.

Usage

You can use this plugin either in a pipeline or as a post-build action.

Pipeline

The plugin is compatible with the pipeline plugin and can be configured to support many use cases. You probably want to adjust it using the Snippet Generator.

The gitChangelog step can return:

  • Context - An object that contains all the information needed to create a changelog. Can be used to gather information from Git like committers, emails, issues and much more.
  • String - A string that is a rendered changelog, ready to be published. Can be used to publish on build summary page, on a wiki, emailed and much more.

The template and context is documented here.

It can integrate with issue management systems to get titles of issues and links. You will probably want to avoid specifying credentials in plain text in your script. One way of doing that is using the credentials binding plugin. The supported integrations are:

  • GitLab
  • GitHub
  • Jira

You can create a file or maby publish the changelog with:

You can filter out a subset of the commits by:

  • Specifying specific from/to references/commits.
  • Adding filter based on message.
  • Adding filter based on commit time.
  • Filter tags based on tag name.
  • Filter commits based on commit time.
  • Ignore commits that does not contain an issue.

You can make the changelog prettier by:

  • Transforming tag name to something more readable.
  • Changing date display format.
  • Creating virtual tag, that contains all commits that does not belong to any other tag. This can be named something like Unreleased.
  • Creating virtual issue, that contains all commits that does not belong to any other issue.
  • Remove issue from commit message. This can be named something like Wall of shame and list all committers that did not commit on an issue.

Check the Snippet Generator to see all features!

Pipeline with context

Here is an example that clones a repo, gathers all jiras and adds a link to jira in the description of the job. The context contains much more then this and is documented here.

node {
 deleteDir()
 sh """
 git clone git@github.com:jenkinsci/git-changelog-plugin.git .
 """
    
 def changelogContext = gitChangelog returnType: 'CONTEXT',
  from: [type: 'REF', value: 'git-changelog-1.50'],
  to: [type: 'REF', value: 'master'],
  jira: [issuePattern: 'JENKINS-([0-9]+)\\b', password: '', server: '', username: '']

 Set<String> issueIdentifiers = new TreeSet<>()
 changelogContext.issues.each { issue ->
  if (issue.name == 'Jira') {
   issueIdentifiers.add(issue.issue)
  }
 }
 currentBuild.description = "http://jira.com/issues/?jql=key%20in%20%28${issueIdentifiers.join(',')}%29"
}

Pipeline with string

Here is an example that clones a repo and publishes the changelog on job page. The template and context is documented here.

node {
 deleteDir()
 sh """
 git clone git@github.com:jenkinsci/git-changelog-plugin.git .
 """
    
 def changelogString = gitChangelog returnType: 'STRING',
  from: [type: 'REF', value: 'git-changelog-1.50'],
  to: [type: 'REF', value: 'master'],
  template: """
 <h1> Git Changelog changelog </h1>

<p>
Changelog of Git Changelog.
</p>

{{#tags}}
<h2> {{name}} </h2>
 {{#issues}}
 {{#hasIssue}}
 {{#hasLink}}
<h2> {{name}} <a href="{{link}}">{{issue}}</a> {{title}} </h2>
 {{/hasLink}}
 {{^hasLink}}
<h2> {{name}} {{issue}} {{title}} </h2>
 {{/hasLink}}
 {{/hasIssue}}
 {{^hasIssue}}
<h2> {{name}} </h2>
 {{/hasIssue}}


 {{#commits}}
<a href="https://github.com/tomasbjerre/git-changelog-lib/commit/{{hash}}">{{hash}}</a> {{authorName}} <i>{{commitTime}}</i>
<p>
<h3>{{{messageTitle}}}</h3>

{{#messageBodyItems}}
 <li> {{.}}</li> 
{{/messageBodyItems}}
</p>


 {{/commits}}

 {{/issues}}
{{/tags}}
 """

 currentBuild.description = changelogString
}

Post-build action

When the plugin is installed, it will add some new post build actions in Jenkins job configuration.

There are duplicated features here because this plugin is a merge of 2 plugins!

Git Changelog

A couple of revisions are configured along with some other optional features. A editable template is available for the user to tweak.

Select references

The changelog is created from parsing Git and rendering the template with a context derived from the configured revisions.

Tweak template

Publish JIRA Filter

The following documentation explains to set up the JIRA Filter post-build action. Using the basic changelog post-build action is even easier, as it does not need any further configuration.

On any jenkins project using Git as Source Code Management, add "Publish JIRA Filter" Post-build Action. A form with a few input fields appears where you can configure the behaviour. Just below the input fields their meaning and default behaviour is explained.

If you leave the file input empty, the information will be logged into the jenkins console.

If you specify a filename, you can use other plugins like HTML Publisher Plugin to save the files as jenkins report.

Publish Git Changelog

A couple of revisions are configured and an output file will be created with the changes between them.

Using as Token Macro Replacement Provider

Having installed the Token Macro Plugin plugin (which will be the case, as it is a dependency of this plugin), following macros for replacement are provided: GITCHANGELOGJIRA and GITCHANGELOG.

The Publish Git Changelog provides macro GITCHANGELOGJIRA and Publish JIRA Filter provides macro GITCHANGELOG. The Git Changelog post-build step does not provide a macro, instead use pipelines!

If you use these macros in any plugin supporting token macro replacements, this will be replaced with either the Jira URL or the changelog.

The Email-ext plugin supports token macros, so you can include this URL in an automatically sent email.

Development

This plugin can be built and started with maven and Jenkins' hpi plugin:

./run.sh

The functionality is implemented in git-changelog and git-changelog-lib. Pull requests are welcome!

17 Comments

  1. Hi,

    plugin does not parse environment variables in the file path

    also there is a problem when put commit hash to toRev field (error Ref <git_commit> not found.)

  2. Error editing any Jenkins project with v1.2 installed. See attached for full stack trace.

    git-changelog-error.txt

  3. I can't figure out how to configure this plugin as shown here:http://stackoverflow.com/questions/36016043/how-to-set-up-git-changelog-in-jenkins. I think you should provide another screenshot on how to configure the Publish Git changelog plugin.

  4. I am having this can't delete workspace issue with this plugin: Jenkins ver. 1.638 on" class="external-link" rel="nofollow">https://issues.jenkins-ci.org/browse/JENKINS-19994.&nbsp;Jenkins ver. 1.638&nbsp;on Windows 2012.

    1. Which version of GIT Plugin do you use? The one required by this plugin may contain bugs, so udating to GIT Plugin 2.4.3 may help you.

  5. Hi,

    I am using jenkins version 1.611 and Java version 1.6. I could not run the latest version of the Git changelog plugin with JDK 1.6. Tried to look up previous version and its dependency versions and could not figure out as any history page I look up it always shows the latest updated page data.

    I have some limitations in upgrading the JDK version on the CI machine.

    Can you please help me get the version details of this plugin and its dependencies that work on JDK 1.6?

    Regards,
    Ramki

  6. We're interested to produce changelog between Git code in  our previous and current build. I mean, "from" reference should be Git branch from the previous job, and "to" should be Git branch in our current job.
    Is there a way to do this with the Git Changelog plugin?

    thanks, Vitaly

    1. "You may want to use variables provided by the Git Plugin to create a changelog from GIT_PREVIOUS_SUCCESSFUL_COMMIT to GIT_COMMIT or perhaps just GIT_PREVIOUS_COMMIT to GIT_COMMIT."

      1. Thank you, I'll try!

  7. Is it possible to configure so that the changelog contains the files in a commit?

    Btw, a great plugin!

  8. Hi While pushing the change log tomediawiki iam getting the below issue, can anyone let me know what could be the issue  

    --- Git Changelog ---
    ---
    ERROR: Step ‘Git Changelog’ aborted due to exception: 
    java.lang.ClassNotFoundException: com.google.gson.Gson
    	at java.net.URLClassLoader.findClass(Unknown Source)
    	at java.lang.ClassLoader.loadClass(Unknown Source)
    	at java.lang.ClassLoader.loadClass(Unknown Source)
    Caused: java.lang.NoClassDefFoundError: com/google/gson/Gson
    	at se.bjurr.gitchangelog.internal.settings.Settings.<clinit>(Settings.java:34)
    	at se.bjurr.gitchangelog.api.GitChangelogApi.<init>(GitChangelogApi.java:430)
    	at se.bjurr.gitchangelog.api.GitChangelogApi.gitChangelogApiBuilder(GitChangelogApi.java:57)
    	at org.jenkinsci.plugins.gitchangelog.perform.RemoteCallable.call(RemoteCallable.java:55)
    	at org.jenkinsci.plugins.gitchangelog.perform.RemoteCallable.call(RemoteCallable.java:28)
    	at hudson.FilePath.act(FilePath.java:1083)
    	at org.jenkinsci.plugins.gitchangelog.perform.GitChangelogPerformer.performerPerform(GitChangelogPerformer.java:40)
    	at org.jenkinsci.plugins.gitchangelog.GitChangelogRecorder.perform(GitChangelogRecorder.java:52)
    	at hudson.tasks.BuildStepCompatibilityLayer.perform(BuildStepCompatibilityLayer.java:78)
    	at hudson.tasks.BuildStepMonitor$1.perform(BuildStepMonitor.java:20)
    	at hudson.model.AbstractBuild$AbstractBuildExecution.perform(AbstractBuild.java:779)
    	at hudson.model.AbstractBuild$AbstractBuildExecution.performAllBuildSteps(AbstractBuild.java:720)
    	at hudson.model.Build$BuildExecution.post2(Build.java:186)
    	at hudson.model.AbstractBuild$AbstractBuildExecution.post(AbstractBuild.java:665)
    	at hudson.model.Run.execute(Run.java:1753)
    	at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
    	at hudson.model.ResourceController.execute(ResourceController.java:98)
    	at hudson.model.Executor.run(Executor.java:405)
    Finished: FAILURE
  9. Is there any support for git submodules with this plugin?  I'd like to have the change log include all changes from any submodule updates in my multi branch pipline.

  10. It seems like this doesn't respect the "Unique SCM Name" setting in the the Modern SCM Git plugin's Additional Behaviours. So if you have multiple SCMs you get a changelog that's a bit of a mismash.