Document requirement for Docker executor image ENTRYPOINT to support sh/bash COMMAND

Pierre Beucherrequested to merge
pbeucher/gitlab-runner:docs-docker-executor-entrypoint-sh into main

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

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 like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure 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.

Merge request reports