The Source-to-Image (S2I) Process

Source-to-image Build Process

Source-to-image (S2I) produces ready-to-run images by injecting source code into a container that prepares that source code to be run. It performs the following steps:

  • Runs the FROM <builder image> command
  • Copies the source code to a defined location in the builder image
  • Runs the assemble script in the builder image
  • Sets the run script in the builder image as the default command
  • Buildah then creates the container image.

Anatomy of a builder image Creating builder images is easy. s2i looks for you to supply the following scripts to use with an image:

  • assemble - builds and/or deploys the source
  • run- runs the assembled artifacts
  • save-artifacts (optional) - captures the artifacts from a previous build into the next incremental build
  • usage (optional) - displays builder image usage information

Additionally, for the best user experience and optimized s2i operation we suggest images to have /bin/sh and tar commands available.

Build Workflow

The s2i build workflow is:

  • s2i creates a container based on the build image and passes it a tar file that contains:
    • The application source in src, excluding any files selected by .s2iignore
    • The build artifacts in artifacts (if applicable - see incremental builds)
  • s2i sets the environment variables from .s2i/environment (optional)
  • s2i starts the container and runs its assemble script
  • s2i waits for the container to finish
  • s2i commits the container, setting the CMD for the output image to be the run script and tagging the image with the name provided.

Filtering the contents of the source tree is possible if the user supplies a .s2iignore file in the root directory of the source repository, where .s2iignore contains regular expressions that capture the set of files and directories you want filtered from the image s2i produces.


  • Specify one rule per line, with each line terminating in \n.
  • Filepaths are appended to the absolute path of the root of the source tree (either the local directory supplied, or the target destination of the clone of the remote source repository s2i creates).
  • Wildcards and globbing (file name expansion) leverage Go's filepath.Match and filepath.Glob functions.
  • Search is not recursive. Subdirectory paths must be specified (though wildcards and regular expressions can be used in the subdirectory specifications).
  • If the first character is the # character, the line is treated as a comment.
  • If the first character is the !, the rule is an exception rule, and can undo candidates selected for filtering by prior rules (but only prior rules).

Here are some examples to help illustrate:

With specifying subdirectories, the /temp rule prevents the filtering of any files starting with temp that are in any subdirectory that is immediately (or one level) below the root directory. And the //temp* rule prevents the filtering of any files starting with temp that are in any subdirectory that is two levels below the root directory.

Next, to illustrate exception rules, first consider the following example snippet of a .s2iignore file:


With this exception rule example, will not be filtered, and remain in the image s2i produces. However, with this snippet:

*.md, if filtered by any prior rules, but then put back in by !, would be filtered, and not part of the resulting image s2i produces. Since *.md follows !, *.md takes precedence.

Users can also set extra environment variables in the application source code. They are passed to the build, and the assemble script consumes them. All environment variables are also present in the output application image. These variables are defined in the .s2i/environment file inside the application sources. The format of this file is a simple key-value, for example:


In this case, the value of FOO environment variable will be set to bar.