Skip to main content
When TrueFoundry builds a Docker image for a service, job, workflow, or other workload, it runs a fixed sequence of steps: download code, log in to the registry, build the image, and push it. You can customize this build workflow by overriding the main build script and adding your own logic-for example, security scans, tests, or custom tooling-before, during, or after those steps. Your custom script runs in order with the platform’s built-in steps.
This customization applies to the platform-level build workflow (Helm values). It affects how images are built whenever the platform builds an image for any service, job, or workflow.

​
When would you use this?

Common use cases:
  • Security or quality checks: Run a scanner (e.g. SonarQube, Trivy) on the source before building.
  • Pre-build steps: Install tools, run linters, or run tests before the image is built and pushed.
  • Post-build steps: Notify external systems, tag images, or run checks after the image is pushed.
You do this by writing a custom script, putting it in a ConfigMap so the build pod can run it, and then wiring it into the platform’s build script in Helm. Follow the steps below.

​
What the build script looks like

The platform runs a main build script for every image build: a sequence of steps. You override it in Helm and insert calls to your custom script where you want (before, during, or after the built-in steps). The default sequence is:
  1. download-code.sh - fetch source code
  2. registry-login.sh - log in to the container registry
  3. wait-for-builder.sh - wait for the builder
  4. build-and-push.sh - build the image and push it
  5. update-build.sh - report build status
Your custom script is mounted at /custom-scripts/ in the build pod. In the main script you add a line like /custom-scripts/<your-script-filename> where you want it to run-e.g. after step 1 (pre-build scan) or after step 4 (post-build notify). The structure looks like this: 
script: |
  download-code.sh

  # Your custom script runs here (e.g. scan, test, lint)
  /custom-scripts/<your-script-filename>

  registry-login.sh
  wait-for-builder.sh
  build-and-push.sh

  # Or run it here (e.g. notify, tag)
  # /custom-scripts/<your-script-filename>

  update-build.sh '{"status":"SUCCEEDED"}'
Do not remove any of the existing steps (download-code.sh, registry-login.sh, wait-for-builder.sh, build-and-push.sh, update-build.sh) from the script. Removing them can break the build workflow.
Once you know where your script fits in this sequence, you can write the script (Step 1), put it in a ConfigMap (Step 2), and then add the full configuration in Helm (Step 3).

​
Add custom logic to the build pipeline

1

Write your custom script

A script here is a bash file that runs inside the build pod when the platform builds an image.You write it once; in the next steps you’ll put it in a ConfigMap, mount it at /custom-scripts/, and call it from the main build script (e.g. /custom-scripts/scan-before-build.sh) at the point you choose-before, during, or after the built-in steps. You’re defining the logic that runs at that point (e.g. a scan, test, or notification).Create a bash script with that logic. Remember the filename-you’ll use it for the ConfigMap (Step 2) and for the invocation line in the main build script (Step 3).Example: scanning source code with SonarQube before the image is built and pushed:
#!/bin/bash

# Example: scan source code using SonarQube
# Ref: https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/sonarscanner/#running-from-zip-file
sonar-scanner $SOURCE_CODE_DOWNLOAD_PATH -Dsonar.token=$SONARQUBE_AUTH_TOKEN
Use the absolute path when invoking your script from the build workflow (e.g. /custom-scripts/scan-before-build.sh). The default working directory in the build pod is /scripts.
Environment variables: If your script needs extra env vars, add them in Step 3 under tfyBuild.truefoundryWorkflows.extraEnvs. Do not overwrite these reserved variables: SOURCE_CODE_DOWNLOAD_PATH, DOCKER_REGISTRY_URL, DOCKER_REGISTRY_USERNAME, DOCKER_REGISTRY_PASSWORD, DOCKER_REPO, DOCKER_TAG, CALLBACK_URL. You can read and use them in your script if needed.
2

Create a ConfigMap from your script

The build workflow runs in a pod that must have access to your script. A ConfigMap stores the script so the pod can mount it as a file.Create the ConfigMap so the script is available when the build runs:
kubectl create configmap <configmap-name> --from-file=<script-file-name> -n truefoundry
Example: if your script is scan-before-build.sh and you want the ConfigMap named my-build-scripts:
kubectl create configmap my-build-scripts --from-file=scan-before-build.sh -n truefoundry
3

Add your script to the TrueFoundry build workflow

You need to:
  1. Mount the ConfigMap so the build pod can read your script from /custom-scripts/.
  2. Set the main build script in Helm so it calls your script at the right place (see What the build script looks like for the sequence).
In your Helm values, set tfyBuild.truefoundryWorkflows as below. Replace <config-map-name> with the ConfigMap from Step 2, and <your-script-filename> with the script file from Step 1 (e.g. scan-before-build.sh).
Keep all existing steps in the script. Do not remove download-code.sh, registry-login.sh, wait-for-builder.sh, build-and-push.sh, or update-build.sh.
Set defaultMode: 511 on the ConfigMap volume so the mounted script file is executable.
tfyBuild:
  truefoundryWorkflows:
    extraVolumes:
      - name: custom-script
        configMap:
          name: <config-map-name>
          defaultMode: 511
    extraVolumeMounts:
      - name: custom-script
        mountPath: /custom-scripts
    sfyBuilder:
      script: |
        download-code.sh

        # Run your script from Step 1 (mounted at /custom-scripts/)
        /custom-scripts/<your-script-filename>

        registry-login.sh
        wait-for-builder.sh
        build-and-push.sh

        # Optional: run another script from Step 1 after build and push (e.g. notify, tag)
        # /custom-scripts/<your-script-filename>

        update-build.sh '{"status":"SUCCEEDED"}'
  • extraVolumes / extraVolumeMounts: Mount your ConfigMap at /custom-scripts so the pod can execute your script.
  • defaultMode: 511: Makes the file executable (required for the script to run).
  • sfyBuilder.script: This is the main build script that runs for every image build. The logic you add here (including calls to /custom-scripts/...) runs in order with the built-in steps.
To pass environment variables to your custom script, add them under tfyBuild.truefoundryWorkflows.extraEnvs. Do not overwrite the reserved variables listed in Step 1.
After you apply these values and the platform runs a build, it will use this script and your custom logic will run at the positions you defined.