Skip to end of metadata
Go to start of metadata

Plugin Information

View Shelve Project 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:

This plugin lets you shelve projects so that they can easily be resurrected."Shelving a project" is like deleting a project into a recycle bin. When you shelve a project, it'll disappear from the list of projects and become inaccessible from Jenkins, just like how it goes when a project is deleted, with one difference — instead of getting deleted, the data is archived into a zip file and stored on the server. This allows the administrator to resurrect it later (aka unshelving), in an unlikely event that the job turned out to be necessary.

This feature is convenient when you have lots of old jobs lying around, and you are 99% sure you won't need them but you can't rule out 1% possibility that you might find them necessary later.

Usage

When you install this plugin, you get "shelve project" in each job page, as follows:

You can click this icon and shelve the project. The shelved projects can be resurrected from the Jenkins top page, with the following UI:

Security

If security settings are enabled in Jenkins, shelving a project requires DELETE permissions and unshelving a project requires CREATE permissions.

Known issue and workaround

There is a currently a known issue in Core, making the tar function breaking the symlinks. Sadly, the Shelve Pipeline Plugin is using this tar function, and therefore the symlinks are lost during the shelving/unshelving process.

Up until Jenkins 2.90, this was mainly hidden from the end user, as Jenkins was silently fixing the symlinks during a build. But since this version, some changes made this issue visible.

This means that, when you unshelve a job, you will see a stack trace like this in all your build logs:

ln builds/lastSuccessfulBuild ***/jenkins-home/jobs/toto/lastSuccessful failed
java.nio.file.DirectoryNotEmptyException: ***/jenkins-home/jobs/toto/lastSuccessful
	at sun.nio.fs.UnixFileSystemProvider.implDelete(UnixFileSystemProvider.java:242)
	at sun.nio.fs.AbstractFileSystemProvider.deleteIfExists(AbstractFileSystemProvider.java:108)
	at java.nio.file.Files.deleteIfExists(Files.java:1165)
	at hudson.Util.createSymlink(Util.java:1333)
	at hudson.model.Run.createSymlink(Run.java:1866)
	at hudson.model.Run.updateSymlinks(Run.java:1847)
	at hudson.model.Run.execute(Run.java:1725)
	at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:43)
	at hudson.model.ResourceController.execute(ResourceController.java:97)
	at hudson.model.Executor.run(Executor.java:421)

While this won't affect the output of your build, this is far from convenient. A workaround for this issue is to manually delete the wrongly created files using something like:


First make a dry run to ensure the script is not deleting something it shouldn't:


find ${JENKINS_HOME}/jobs/ -type d \( -name lastFailedBuild -o -name lastSuccessfulBuild -o -name lastUnsuccessfulBuild -o -name lastStableBuild -o -name lastUnstableBuild -o -name lastFailed -o -name lastSuccessful -o -name lastUnsuccessful -o -name lastStable -o -name lastUnstable \)


Then, do the real cleaning:

find ${JENKINS_HOME}/jobs/ -type d \( -name lastFailedBuild -o -name lastSuccessfulBuild -o -name lastUnsuccessfulBuild -o -name lastStableBuild -o -name lastUnstableBuild -o -name lastFailed -o -name lastSuccessful -o -name lastUnsuccessful -o -name lastStable -o -name lastUnstable \) -exec rm -rfv "{}" \;


Version History

Version 2.2 (2018-11-13)

Version 2.1 (2018-07-20)

The way a project is backed up has now changed from zip to tar. This is mainly a detail of implementation for you as your currently shelved project can still be unshelved from zip files.

However if you have some sort of automation on the shelved project directory (backup of the projects elsewhere for instance), you might need to adapt your script to look for tars instead of zips.


  • Take folders into account when shelving/unshelving (JENKINS-43434).
  • Do not use a JobProperty to add the shelve action (JENKINS-39929).
  • Failure to display the shelve icon on the job page should have disappeared.
  •  Symlinks are now correctly unshelved.

Version 2.0 (2018-07-15)

  • Switch development and tests to java 8.
  • Bump minimum Jenkins core to 2.60.3.
  • Various development third parties updates (JUnit...).
  • Jenkinsfile for automated build of the plugin in the Jenkins infra.
  • Fixed various issues detected by newly integrated tools (findbugs...).
  • Fix security issue

Version 1.5 (2014-04-18)

  • Ability to delete shelved projects ( JENKINS-11374 )
  • Bug fix on updated config ( JENKINS-10544 )
  • Bug fix ( JENKINS-8063 )
  • Hygienic updates (rev JUnit, base plugin version, port to JenkinsRule for unit tests...)

Version 1.4.4 (2013-07-29)

  • Wipe out workspace while shelving project (this saves disk usage). (issue #11023)

Version 1.3 (2011-08-06)

  • Sort list of shelves projects by the project name. (JENKINS-8570)
  • Allow unshelving of multiple projects at the same time. (JENKINS-8571)
  • Don't display full path for archive when unshelving. (JENKINS-8759)

Version 1.2 (2011-02-08)

  • Update for Jenkins.

Version 1.1 (2010-11-05)

  • Update code making it compatible with Hudson 1.383. Older versions of Hudson received 500 errors because the method "getEstimatedDuration" was unimplemented. (JENKINS-8016)

Version 1.0 (2010-10-18)

Version 0.3 (2010-02-27)

  • Reload Hudson configuration after unshelving a project. (JENKINS-5425)
  • Hudson version 1.336 or newer is now required for reloading Hudson's configuration after  unshelving a project.

Version 0.2 (2010-01-25)

Version 0.1 (2010-01-05)

  • Initial release

Todo

  • How to handle workspaces?
    • Shelving a project running on master works - however, the project's workspace located on the master is archived
    • Shelving a project running on a slave works - however, project's workspace located on the slave is not archived

19 Comments

  1. More details please?  I'm interested but I'd like to know exactly what it does.

  2. Unknown User (nandini.obhrai@gmail.com)

    Can we call this plugin via url post to <hudsonserver>\shelve\shelveproject

    1. Yes you can by do this by sending a GET or POST to HUDSON_URL/job/JOBNAME/shelve/shelveProject.

  3. Generally I'm interested in config.xml, and maybe changelog.xml, but I definitely do not want to archive the workspace or old artifacts - these would be far too big. Is it supported to shelve just metadata?

    1. Hi Jesse. If you don't want the workspace, you can wipe it before shelving. Maybe, as an option, the Shelve Plugin should nag you if you try to shelve a project with a workspace - and offer to wipe it first.

  4. When will 1.3 be released? It's been two months now...

  5. Hello,

    Nice plug-in

    Could we download/upload shelves project?

    Could you add project description in shelve project list?

    Regards,

    Arnaud.

  6. I am using Jenkins on Linux. 

    When projects are zipped all symbolic links in the project's "builds" directory are converted to dir copies in the archive. Same happens to lastSuccessful and lastStable links. It effectively doubles the size of the project after a shelve-unshelve cycle. Also having two copies of a build also creates a potential for errors.

    Probably it should be reported as an issue.

    1. I filed  an issue https://issues.jenkins-ci.org/browse/JENKINS-10986 

      I also attached a fix for this issue. The fix work for me. The fix is not properly reviewed or tested and produces one unhandled exception.

    2. For large projects this can be really a problem when suddenly all the symlinks are converted into actual content.

  7. 'Shelved Projects' link is not shown in some projects...

    Jenkins ver. 1.423, plugin ver. 1.3

  8. Hello,

    I have one question to You.
    When You use "shelve-project-plugin", Jenkins works faster?
    I must save server resources and I want to know if it help me.
    Please, devide with me your experience from work with this plugin.

    :)

    1. Faster? Why would this make Jenkins faster? It simply zips your the jobs/[JOB_NAME] and then deletes that directory so that Jenkins doesn't "know" about it until you unshelve it.  What resources are you having trouble with?  If it's java heap space on the master, simply increase the java heap space of the master (we have 500+ jobs with 25 slaves, and we have the master set at 512MB minimum and 3096MB maximum, and we have no problems.)  If you're running out diskspace on the master, then only archive what you absolutely need and delete old jobs/artifacts that you don't need.  Good luck!

  9. K X

    Is there a way to mass shelve projects using Jenkins cli or some other way?

    Got 190 jobs that need to be shelved but going 1 by 1 is not an option.

  10. I'm getting an exception each time I run the plugin (shelving or un-shelving). The plugin still runs (the project is shelved or un-shelved as expected), but the entire time it's running my console log gets spammed with "WARNING: Caught exception evaluating: e.hasStopPermission(). Reason: java.lang.NullPointerException" and a stack trace starting at "at hudson.model.Executor.hasStopPermission(Executor.java:497)".

    I've confirmed that the user account used to run the job is set up with full access in my Jenkins security matrix (Security Realm: Unix user/group database; Authorization: Matrix-based Security).

    Edit: I'm running Jenkins v1.451.

    Does anyone have an idea why this may be happening?

    Thanks!

  11. How well does this Shelve plugin work with the SCM Sync plugin?  There are already issues with SCM Sync when you rename a project (the SCM Sync 0.0.9 revision was supposed to fix this but introduces a serious "UI goes blank" error).  I'm concerned Shelving a build task will result in issues with the repository updates from SCM Sync.

  12. If security settings are enabled in Jenkins, shelving a project requires DELETE permissions and unshelving a project requires CREATE permissions.

    I enabled user access to delete the job under manage role settings, but they are not seeing "Shelve Project" option, Can you please help me here? 

  13. Option to shelve is not available for pipeline type jobs. Guess I will have to do it manually.

  14. I would like to request a feature:
    Delete after date.

    Set a date for a job that has been shelved so that it will be deleted after that date?
    I see that there's a date for when the job was shelved already. Just need a date for when it should be deleted and trigger the delete.

    Or maybe even a global configuration for how long to keep shelved jobs.

    Thanks! Great plugin!