Uploaded image for project: 'Jenkins'
  1. Jenkins
  2. JENKINS-64469

How to get value of recipient providers

    XMLWordPrintable

    Details

    • Similar Issues:

      Description

      I want to start using the email-ext plugin more extensively but I am very deeply concerned with spamming e-mails to people I don't intend to send e-mails to.

      I would like to use the various recipientProviders available but I would like to be able to experiment with them before actually starting to use them in any e-mails.

      What would be most useful would be to be able to have them resolve into some kind of string that I could simply display in a Pipeline job. Something like:

      println value_of([$class: 'DevelopersRecipientProvider'])
      

      Actually even an option to this plugin to operate in "dry-run" mode where it logs the result of what it would do in a the step's output but not actually send any e-mails would suffice.

      As an aside, do any of the existing recipientProviders represent the committer? I.e. would be the person ultimately responsible for every commit that goes on to a branch, no matter who the author is.

      Nominally, the committer and author are usually the same person, but merge commits (i.e. merge from master to my branch to get my branch up to date with master) could conceivably make these different where the author of a merge commit is the authors of all of the commits that get merged into my branch, correct?  This kind of "unknown" is what really scares me about starting to use the recipientProviders without first being able to experiment with their values in a way that does not result in me unintentionally spamming.

      TBH, I find the descriptions of what the various providers resolve to to be quite fuzzy – hence why I want to be able to experiment with them before spamming with them.

        Attachments

          Activity

          Hide
          basil Basil Crow added a comment -

          Hey Brian J Murrell, I just started maintaining this plugin recently and I share your frustration at the terse documentation for the various recipient providers. I don't understand all of them yet myself! Don't be afraid to dive into the source code if some particular aspect of their behavior is unclear. And if you see a way that the descriptions could be improved, feel free to file a PR to clarify the help text.

          (Another, slightly more advanced, way of learning about these recipient providers is to read (or write!) an integration test for one of them. This requires some basic knowledge of Jenkins internals but it can be very helpful. For example, I recently wrote UpstreamComitterRecipientProviderTest, which taught me a lot about how UpstreamComitterRecipientProvider works and allowed me to step through it in the debugger while running various Pipeline jobs. Test coverage for the recipient providers is incomplete, but perhaps an existing test will answer some of your questions. And if not, adding test coverage gives you a chance to answer your questions about the recipient provider with the benefit of an IDE's debugger.)

          Something like value_of([$class: 'DevelopersRecipientProvider']) could be implemented as a new step, at the same level as EmailExtRecipientStep, but that may be overkill: steps require a lot of boilerplate code, and I don't get the sense that a value_of step would be used all that much except during the development of a Pipeline job. Another downside is that this would only work for Pipeline jobs, not Freestyle jobs (note that this plugin supports both).

          The "dry run" mode you have proposed seems to be a better fit. It could be implemented in ExtendedEmailPublisher, which is used for both Freestyle and (via EmailExtRecipientStep) Pipeline jobs. This would be simpler to implement since it doesn't require a custom step; rather, in ExtendedEmailPublisher#sendMail we could let the code run past the part where it prints "Sending email to:" and then just return early in dry-run mode before it gets to Transport transport = session.getTransport(); (where it makes the connection to the mail server and sends the message). This also has the benefit of being a fairly realistic dry-run, since we would execute all normal code paths right up to the point where the message would otherwise be sent. If you're interested in working on a dry-run mode, PRs are welcome! I'd be happy to review and eventually release such a feature.

          Show
          basil Basil Crow added a comment - Hey Brian J Murrell , I just started maintaining this plugin recently and I share your frustration at the terse documentation for the various recipient providers. I don't understand all of them yet myself! Don't be afraid to dive into the source code if some particular aspect of their behavior is unclear. And if you see a way that the descriptions could be improved, feel free to file a PR to clarify the help text. (Another, slightly more advanced, way of learning about these recipient providers is to read (or write!) an integration test for one of them. This requires some basic knowledge of Jenkins internals but it can be very helpful. For example, I recently wrote UpstreamComitterRecipientProviderTest , which taught me a lot about how UpstreamComitterRecipientProvider works and allowed me to step through it in the debugger while running various Pipeline jobs. Test coverage for the recipient providers is incomplete, but perhaps an existing test will answer some of your questions. And if not, adding test coverage gives you a chance to answer your questions about the recipient provider with the benefit of an IDE's debugger.) Something like value_of( [$class: 'DevelopersRecipientProvider'] ) could be implemented as a new step, at the same level as EmailExtRecipientStep , but that may be overkill: steps require a lot of boilerplate code, and I don't get the sense that a value_of step would be used all that much except during the development of a Pipeline job. Another downside is that this would only work for Pipeline jobs, not Freestyle jobs (note that this plugin supports both). The "dry run" mode you have proposed seems to be a better fit. It could be implemented in ExtendedEmailPublisher , which is used for both Freestyle and (via EmailExtRecipientStep ) Pipeline jobs. This would be simpler to implement since it doesn't require a custom step; rather, in ExtendedEmailPublisher#sendMail we could let the code run past the part where it prints "Sending email to:" and then just return early in dry-run mode before it gets to Transport transport = session.getTransport(); (where it makes the connection to the mail server and sends the message). This also has the benefit of being a fairly realistic dry-run, since we would execute all normal code paths right up to the point where the message would otherwise be sent. If you're interested in working on a dry-run mode, PRs are welcome! I'd be happy to review and eventually release such a feature.
          Hide
          basil Basil Crow added a comment -

          Actually looks like this already exists (but is not documented!) in the form of the emailextrecipients step.

          Show
          basil Basil Crow added a comment - Actually looks like this already exists (but is not documented!) in the form of the emailextrecipients step .
          Hide
          brianjmurrell Brian J Murrell added a comment -

          Basil Crow Can you expand?

          I can clearly see that the various recipient providers are documented there, but nothing about how to get their values, or do a dry-run of any sort that results in getting the values without actually ending e-mail (spamming) them.

          Show
          brianjmurrell Brian J Murrell added a comment - Basil Crow  Can you expand? I can clearly see that the various recipient providers are documented there, but nothing about how to get their values, or do a dry-run of any sort that results in getting the values without actually ending e-mail (spamming) them.
          Hide
          basil Basil Crow added a comment -

          Well, I did write that emailextrecipients is not documented, didn't I? Unfortunately you're going to have to read the source code to figure out how to invoke it. From first glance it looks like it is invoked with a list of recipient providers and returns a string of the email addresses that the message would be sent to, but I've never actually tried it. (It was written by the previous maintainer of this plugin.) If you figure out how to use it, feel free to submit a PR to add some documentation!

          Show
          basil Basil Crow added a comment - Well, I did write that emailextrecipients is not documented, didn't I? Unfortunately you're going to have to read  the source code to figure out how to invoke it. From first glance it looks like it is invoked with a list of recipient providers and returns a string of the email addresses that the message would be sent to, but I've never actually tried it. (It was written by the previous maintainer of this plugin.) If you figure out how to use it, feel free to submit a PR to add some documentation!
          Hide
          brianjmurrell Brian J Murrell added a comment -

          Well, calling it undocumented and then pointing at something written about it was confusing. It's probably more accurate to say that it's poorly documented.

          I added feedback about that page to that effect. However the very long list of unfixed documentation feedback comments doesn't leave me with a warm feeling that the time i spent leaving a comment was time well spent. That spreadsheet looks like a /dev/null to be honest given the number of comments on even just the https://www.jenkins.io/doc/pipeline/steps/email-ext/ page that have not been acted on.

          Anyway, I will look into the emailextrecipients step a bit more. Thanks for the pointer.

          Show
          brianjmurrell Brian J Murrell added a comment - Well, calling it undocumented and then pointing at something written about it was confusing. It's probably more accurate to say that it's poorly documented. I added feedback about that page to that effect. However the very long list of unfixed documentation feedback comments doesn't leave me with a warm feeling that the time i spent leaving a comment was time well spent. That spreadsheet looks like a /dev/null to be honest given the number of comments on even just the https://www.jenkins.io/doc/pipeline/steps/email-ext/ page that have not been acted on. Anyway, I will look into the  emailextrecipients step a bit more. Thanks for the pointer.
          Hide
          basil Basil Crow added a comment -

          pointing at something written

          Well what I pointed at was not written (by a human) but rather autogenerated (by a computer) from EmailExtRecipientStep, as I will explain below.

          I added feedback

          Better would be to open a pull request fixing the problem. Documentation for Pipeline steps is not managed centrally at jenkins-infra/jenkins.io but rather autogenerated from the Jelly code in each plugin's source tree. To fix this, you'll need to add two files to jenkinsci/email-ext-plugin:

          • src/main/resources/hudson/plugins/emailext/EmailExtRecipientStep/help.html (main description for the step)
          • src/main/resources/hudson/plugins/emailext/EmailExtRecipientStep/help-recipientProviders.html (description for the recipientProviders argument to the step)

          Once added, this help text will be visible both in the Snippet Generator (in the Jenkins UI) and in the (autogenerated!) Pipeline Steps Reference.

          have not been acted on

          Because that feedback page is primarily intended for feedback about content managed centrally at jenkins-infra/jenkins.io. Descriptions for Pipeline steps and their arguments do not fall under this category, as explained above.

          Anyway, I will look into the emailextrecipients step a bit more. Thanks for the pointer.

          You're welcome, and good luck! Let me know if you need any more help filing the PR I described above.

          Show
          basil Basil Crow added a comment - pointing at something written Well what I pointed at was not written (by a human) but rather autogenerated (by a computer) from EmailExtRecipientStep , as I will explain below. I added feedback Better would be to open a pull request fixing the problem. Documentation for Pipeline steps is not managed centrally at jenkins-infra/jenkins.io but rather autogenerated from the Jelly code in each plugin's source tree. To fix this, you'll need to add two files to jenkinsci/email-ext-plugin : src/main/resources/hudson/plugins/emailext/EmailExtRecipientStep/help.html (main description for the step) src/main/resources/hudson/plugins/emailext/EmailExtRecipientStep/help-recipientProviders.html (description for the recipientProviders argument to the step) Once added, this help text will be visible both in the Snippet Generator (in the Jenkins UI) and in the (autogenerated!) Pipeline Steps Reference . have not been acted on Because that feedback page is primarily intended for feedback about content managed centrally at jenkins-infra/jenkins.io . Descriptions for Pipeline steps and their arguments do not fall under this category, as explained above. Anyway, I will look into the  emailextrecipients step a bit more. Thanks for the pointer. You're welcome, and good luck! Let me know if you need any more help filing the PR I described above.

            People

            Assignee:
            Unassigned Unassigned
            Reporter:
            brianjmurrell Brian J Murrell
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Dates

              Created:
              Updated: