[JENKINS-71506] Support custom refspec in lightweight checkout

[ckullabosch]

[JENKINS-71506] Support custom refspec in lightweight checkout

Let user specify a custom refspec to fetch. Add support for branch names FETCH_HEAD or a commit hash.

This allows to use lightweight checkout for:

• Fetch the pipeline from a Gerrit change (refspec: refs/changes/*/change/patchset and branch: FETCH_HEAD).

• Fetch the pipeline from a fixed commit of a branch, instead of head (refspec: branch and branch: commit hash).

Checklist

• [x] I have read the CONTRIBUTING doc
• [x] I have referenced the Jira issue related to my changes in one or more commit messages
• [x] I have added tests that verify my changes
• [x] Unit tests pass locally with my changes
• [ ] I have added documentation as necessary
• [x] No Javadoc warnings were introduced with my changes
• [x] No spotbugs warnings were introduced with my changes
• [ ] Documentation in README has been updated as necessary
• [ ] Online help has been added and reviewed for any new or modified fields
• [x] I have interactively tested my changes
• [ ] Any dependent changes have been merged and published in upstream modules (like git-client-plugin)

Types of changes

• [x] New feature (non-breaking change which adds functionality)

[ckullabosch]

@MarkEWaite I think this PR is ready for review. Please let me know if I can do anything to drive the topic forward.

[MarkEWaite]

@MarkEWaite I think this PR is ready for review. Please let me know if I can do anything to drive the topic forward.

Thanks @ckullabosch . It will likely be a week before I'm able to review it due to other priorities. Weekend is coming that may make some time available.

[MarkEWaite]

It would be a great help if you could provide one or more examples in the README.adoc file that show how the custom refespec can be used. The most frequent request from Jenkins documentation readers is a request for more examples. The README file of the git plugin provides many examples in hopes that readers will find them useful. The documentation that you create will also be used as part of my testing of the pull request, so it will help me evaluate the change more effectively.

[MarkEWaite]

With the additional spotbugs checks that were added in #1475 , there is now a spotbugs warning reported for the unread field HeadNameResult.headName. The report seems to be correct because the value of headName that is passed to the HeadNameResult constructor is ignored and replaced with a value computed from the branchSpec.

I suppressed the spotbugs warning in d21149d0380c70d7a2f3ae22895066fe9b49ff3f, but that should be temporary until the root issue can be identified and resolved.

[MarkEWaite]

@ckullabosch I'll need more detailed instructions on the steps that I need to take in order to verify this works as expected. I have been unable to reach the modified code from my job definitions. I created a Pipeline, a multibranch Pipeline, and an organization folder and was unable in any of those cases to see the "Done with " message logged.

Can you provide more details of a way that I can verify the code using GitHub or Bitbucket or GitLab or Gitea? I don't have access to a Gerrit server.

[ckullabosch]

@MarkEWaite In order to try out the change you have to create a Pipeline job which loads the pipeline from SCM (git). You have to enable lightweight checkout (set the checkmark at the end of the job configuration page). Then you may want to experiment with different settings for refspec and branch. There is no need for a folder or multibranch project.

Settings which are possible now, but weren't before:

1. Have a refspec pointing to a branch, point the branch setting to a commit hash (not necessarily the tip of the branch). This lets you use a fixed commit which is not a ref, but contained in the history of a branch.
2. Have a refspec other than refs/tags and refs/heads and make use of "FETCH_HEAD" in the branch setting. The available refs depends on your git system (a branch like refs/heads/my-branch should do as well). In Gerrit you have the refs/changes/, probably other git systems have also special refs (I remember Bitbucket having refs for pull requests).

We need to clarify about improving the README. The lightweight checkout is not mentioned at all at the moment.

[MarkEWaite]

It will be 1-2 weeks before I can review and test this. We're in the last few weeks of Google Summer of Code and I put my efforts there.

[ckullabosch]

@MarkEWaite It's been a while, any chance we can conclude this PR? Please see latest comment of mine.

We need to clarify about improving the README. The lightweight checkout is not mentioned at all at the moment.

[SinOverCos]

@ckullabosch thank you for the PR, I've been looking for something like this.

@MarkEWaite any chance you could give this another pass?

[MarkEWaite]

@MarkEWaite any chance you could give this another pass?

As time allows, I'll do another review. @SinOverCos have you deployed the build of this change into your environment and confirmed that it works for you? It is much more persuasive for a maintainer like me when others users declare that they are using a pull request in production.