How to Pass Custom Environment Variables to Porter Builds

When using Porter's GitHub Actions for deployment, you may need to pass custom environment variables to your builds. This article explains how to properly set up these variables for use in your Porter builds.

Understanding Porter's Environment Variable Handling

Porter only passes environment variables to builds if they are preceded by the prefix PORTER_. This is a security measure to prevent unintended exposure of sensitive information.

Steps to Pass Custom Environment Variables

1. In your GitHub Actions workflow file, locate the step where you run the Porter apply command.

2. In the env section of this step, add your custom environment variables with the PORTER_ prefix.

3. Reference your GitHub secrets using the standard ${{ secrets.SECRET_NAME }} syntax.

Example

Here's an example of how to properly set a custom environment variable (in this case, for a Sentry auth token):

- name: Deploy stack
  timeout-minutes: 30
  run: exec porter apply -f ./porter.yaml
  env:
    PORTER_CLUSTER: "3510"
    PORTER_HOST: https://dashboard.porter.run
    PORTER_PR_NUMBER: ${{ github.event.number }}
    PORTER_PROJECT: "10032"
    PORTER_STACK_NAME: web-prod
    PORTER_TAG: ${{ steps.vars.outputs.sha_short }}
    PORTER_TOKEN: ${{ secrets.PORTER_STACK_10032_3510 }}
    PORTER_SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}
    PORTER_GIT_SHA: ${{ steps.version.outputs.sha_long }}

Note the addition of PORTER_SENTRY_AUTH_TOKEN in the env section. This ensures the Sentry auth token is available in your Porter build.

Accessing Variables in Your Dockerfile

Now, for accessing these variables at build time in your Dockerfile, you need to receive them using the ARG keyword. In our example with the Sentry auth token, this would be like:

ARG PORTER_SENTRY_AUTH_TOKEN

You could, then, turn it into a environment variable in your Dockerfile (with the name you would like) like this:

ENV SENTRY_AUTH_TOKEN=${PORTER_SENTRY_AUTH_TOKEN}

Additional Resources

For more information on build-time environment variables in Porter, refer to our documentation on build-time environment variables.