Document requirement for Docker executor image ENTRYPOINT to support sh/bash COMMAND
What does this MR do?
Document behavior of Docker executor when creating job's container: it uses default ENTRYPOINT
(already documented) but will also override COMMAND
with a complex long command chaining if/else to choose the first available sh
/bash
(effectively passing sh
or bash
as Docker COMMAND
). It's important to understand Docker executor COMMAND
for setting a proper ENTRYPOINT
.
Currently the Docker executor doc specify the need for a valid ENTRYPOINT
, but wording may be better and details are needed for user to understand what is a "valid" ENTRYPOINT
and how COMMAND
will be passed.
if your image defines the ENTRYPOINT and doesn’t allow running scripts with CMD, the image will not work with the Docker executor.
Technical details
Docker executor COMMAND
passed to containers is based on BashDetectShellScript
variable:
const BashDetectShellScript = `if [ -x /usr/local/bin/bash ]; then
exec /usr/local/bin/bash $@
elif [ -x /usr/bin/bash ]; then
exec /usr/bin/bash $@
elif [ -x /bin/bash ]; then
exec /bin/bash $@
elif [ -x /usr/local/bin/sh ]; then
exec /usr/local/bin/sh $@
elif [ -x /usr/bin/sh ]; then
exec /usr/bin/sh $@
elif [ -x /bin/sh ]; then
exec /bin/sh $@
elif [ -x /busybox/sh ]; then
exec /busybox/sh $@
else
echo shell not found
exit 1
fi
`
While it's probably the desired behavior, it's causing confusion when using a Docker image with "invalid" ENTRYPOINT
(such as using echo $@
). For instance a job like:
somejob:
image:
name: alpine
# Setting here for example
# But often something similar is defined as default ENTRYPOINT
entrypoint: ["/bin/sh", "-c", "echo $@"]
script:
- echo "This will never run..."
Will result in executor outputting the content of BashDetectShellScript
(and probably someone being confused), rather than effectively running a sh
before passing script as expected.
Related issues
A quick search with entrypoint
keyword in open issues reveal a few users impacted by this (expected) behavior which looks like a bug:
- #27706 - not a real bug but a user misunderstanding of executor behavior
- #29543 (closed) - user is confused about what shell is used to run job
-
#6698 - user is right: image is missing
sh
/bash
I think the reason is that in the image there's no installed shell so the runner cannot attach himself to the container am I right ?
-
#6584
bash is required in the images that are passed to the runners?
- #4140
Author's checklist
-
Optional. Consider taking the GitLab Technical Writing Fundamentals course. -
Follow the: -
If you're adding or changing the main heading of the page (H1), ensure that the product tier badge is added. -
If you are a GitLab team member, request a review based on: - The documentation page's metadata.
- The associated Technical Writer.
If you are a GitLab team member and only adding documentation, do not add any of the following labels:
~"frontend"
~"backend"
~"type::bug"
~"database"
These labels cause the MR to be added to code verification QA issues.
Reviewer's checklist
Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.
If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.
-
If the content requires it, ensure the information is reviewed by a subject matter expert. - Technical writer review items:
-
Ensure docs metadata is present and up-to-date. -
Ensure the appropriate labels are added to this MR. -
Ensure a release milestone is set. - If relevant to this MR, ensure content topic type principles are in use, including:
-
The headings should be something you'd do a Google search for. Instead of Default behavior
, say something likeDefault behavior when you close an issue
. -
The headings (other than the page title) should be active. Instead of Configuring GDK
, say something likeConfigure GDK
. -
Any task steps should be written as a numbered list. - If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
-
-
-
Review by assigned maintainer, who can always request/require the above reviews. Maintainer's review can occur before or after a technical writer review.