Conditional based on custom environment variable

Pipelines
1

Use-case:
I run the same pipeline in 2 situations: on git push and triggered via API.
I need to distinguish those 2 cases and be able to run different steps for them.
So I assumed it would be logical to pass the env variable that will exist only in the case of API call.
Like API="true" or something similar.
And then in the pipeline have

if: build.env('API') == null

and

if: build.env('API') != null

But this does not seem to work. If I don’t define the custom env var, it just gets ignored.
If I define the custom variable for the pipeline, the value that I set via API does not seem to affect the pipeline upload step. Though it gets propagated inside the steps.

Is there any suggestion whether it should work?
What would be the alternative way to use in conditionals something that I can pass in the API trigger call?
Thanks

2

I can see that I can potentially use BUILDKITE_SOURCE="api"
but it is a bit generic, I’d prefer to have some custom env var if possible

OK, update: I cannot use BUILDKITE_SOURCE
buildkite-agent: fatal: Failed to upload and process pipeline: Pipeline upload rejected: One of the steps you provided was invalid: Error parsing if
2025-05-22 19:13:31 AEST
expression: Interpolation of “BUILDKITE_SOURCE” is not supported (see Environment variables | Buildkite Documentation).
2025-05-22 19:13:31 AEST
You can instead interpolate this variable at runtime (see Environment variables | Buildkite Documentation).

3

more specific example:
I’m trying to achieve something like that

- if: build.env('TEST') == null
  label: ENV VAR STEP
  agents:
    queue: main
  command: exit 1

and be able to pass this env var TEST via API and have it not set when triggered via git push.

4

Hi @MishaLT, welcome to the Buildkite community :) I see that you’ve explored a couple of possible solutions here. It’s true that if you want to use a custom env var, it has to be defined in the pipeline config; you can’t pass in arbitrary ones and have them be instantiated in the build.

The easiest path forward for you might be to use the build.source variable (see Using conditionals | Buildkite Documentation), rather than the BUILDKITE_SOURCE environment variable. You mentioned wanting to be able to use the conditional around the pipeline upload step; this would enable you to do that, and it also avoids the interpolation issue that you ran into. Here’s a simple example:

steps:
  - command: buildkite-agent pipeline upload
    if: build.source == 'webhook'
  - command: buildkite-agent annotate "This build was triggered by the REST API!"
    if: build.source == 'api'

Here, we will call the pipeline upload command if the job is triggered by a webhook, but we will do something different if the REST API was used.

If that doesn’t help get you going, it might be useful if you could contact us by email at support@buildkite.com, and share the details of your build privately, so we can get a better idea of what you are trying to do and craft a solution that will work for you.

5

ok, thanks for the suggestion.
But i’m still wondering if there is any way to have a conditional based on the env var.
I’m not sure if there are any echnical limitations, but it looks like pretty naturally expected behavior TBH.
Thanks

6

Hi @MishaLT ,

As previously suggested, to use env vars in conditionals, you can use the function build.env() to return the value of the environment variable you defined and use it in the conditional, as mentioned in our docs - Using conditionals | Buildkite Documentation.

Cheers!