[JENKINS-49299] Documentation regarding Docker image ENTRYPOINT requirements lacking

Short version:

The fix for -JENKINS-41316- broke my builds.

See recent discussion on pull/116.

Summary:

Expectations and requirements of images (particularly around ENTRYPOINT) behavior need to be clarified and documented better.  The error message that gets reported if ENTRYPOINT does not honor plugin's expectations is misleading and, perhaps, incorrect (regarding "best practices").

Ideally, documentation should be provided which clearly outlines requirements and expectations of images intended for use with the plugin (things like... must contain a shell [bash?], ENTRYPOINT must pass through unexpected args as commands, etc).  And simple workarounds (where possible) should be provided for situations where it is 1) possible to work around and 2) reasonable that an image author might not want or be able to honor plugin's expectations.

In the particular case in question, it would have been helpful if:

• The expectations around ENTRYPOINT were documented


• The build error pointed to Jenkins' docs on the subject instead of misleading Docker docs on it


• A simple workaround given for situations where the ENTRYPOINT doesn't pass-through the CMD (i.e. use a docker arg to override ENTRYPOINT with one that does) most trivially, the workaround could be:

  --entrypoint=""

  
  

  as defined here, to allow the CMD provided to execute without an ENTRYPOINT wrapper.

---
Originally reported by dbingham, imported from: Documentation regarding Docker image ENTRYPOINT requirements lacking

• status: Open
  
• priority: Minor
  
• component(s): docker-workflow-plugin
  
• resolution: Unresolved
  
• votes: 0
  
• watchers: 3
  
• imported: 2025-12-07
  

Raw content of original issue

Short version:


The fix for -JENKINS-41316- broke my builds.


See recent discussion on pull/116.


Summary:


Expectations and requirements of images (particularly around ENTRYPOINT) behavior need to be clarified and documented better.  The error message that gets reported if ENTRYPOINT does not honor plugin's expectations is misleading and, perhaps, incorrect (regarding "best practices").


Ideally, documentation should be provided which clearly outlines requirements and expectations of images intended for use with the plugin (things like... must contain a shell [bash?], ENTRYPOINT must pass through unexpected args as commands, etc).  And simple workarounds (where possible) should be provided for situations where it is 1) possible to work around and 2) reasonable that an image author might not want or be able to honor plugin's expectations.


In the particular case in question, it would have been helpful if:



	
The expectations around ENTRYPOINT were documented

	
The build error pointed to Jenkins' docs on the subject instead of misleading Docker docs on it

	
A simple workaround given for situations where the ENTRYPOINT doesn't pass-through the CMD (i.e. use a docker arg to override ENTRYPOINT with one that does) most trivially, the workaround could be:



--entrypoint=""



as defined here, to allow the CMD provided to execute without an ENTRYPOINT wrapper.

• environment: plugin version 1.15