Recently I came across <a href="https://doppler.com/">Doppler</a> and I wanted to share a specific use case for it.
I'm currently spending some time on a side project where I'm using <a href="https://www.prefect.io/">Prefect</a> to manage my workflows. Despite the fact that I'm not using Prefect in production, I still want to be able to manage my secrets in a secure way and Prefect manages secrets using <a href="https://docs.prefect.io/v3/concepts/blocks">blocks</a> which I'm not a fan of.
<h2 id="why-not-prefect-secret-blocks-directly"><a class="anchor-link" href="#why-not-prefect-secret-blocks-directly">Why not Prefect Secret blocks directly?</a></h2>
<ul>
<li>No environment parity between local and cloud</li>
<li>Secrets tightly coupled to Prefect runtime</li>
<li>Harder to share secrets across non-Prefect services</li>
</ul>
That's where Doppler comes in.
<h2 id="tldr"><a class="anchor-link" href="#tldr">TL;DR</a></h2>
If you already use Prefect and Doppler, skip directly to <a href="#the-code">The code</a> for the implementation.
<h2 id="source-code"><a class="anchor-link" href="#source-code">Source code</a></h2>
The source code for this example is available on <a href="https://github.com/jonatasleon/prefect-doppler-config">GitHub</a>.
<h2 id="doppler"><a class="anchor-link" href="#doppler">Doppler</a></h2>
Doppler is a centralized secret manager that syncs environment-specific secrets to applications via environment variables, SDKs, or CLI, with built-in support for access control, rotation, and multiple deployment environments.
<h3 id="setting-up-doppler-account"><a class="anchor-link" href="#setting-up-doppler-account">Setting up Doppler account</a></h3>
To start using Doppler, it's necessary to create an <a href="https://dashboard.doppler.com/register">account</a>. This setup is pretty straightforward and I recommend to follow the <a href="https://docs.doppler.com/docs/getting-started">official documentation</a> to complete it.
Note that you don't need to provide credit card information to start using the service.
<h3 id="setting-up-a-project"><a class="anchor-link" href="#setting-up-a-project">Setting up a project</a></h3>
<ol>
<li>
For this example, I'll create a project called <code>my-project</code>:
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-qufz.webp" alt="Creating a project" width="532" height="439" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
As soon as we create the project, Doppler automatically creates three environments and their slugs: Development(<code>dev</code>), Staging(<code>stg</code>) and Production(<code>prd</code>).
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-qvxj.webp" alt="Created environments" width="1045" height="392" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Let's define a secret called <code>SECRET_API_KEY</code> and we'll set the value to <code>1234567890</code>. After entering the value, click the Save button.
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-qxhf.webp" alt="Creating a secret" width="1200" height="232" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
After saving, Doppler will ask whether you want to propagate this secret. You can choose to propagate it to all environments or just to the selected ones.
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-qxyi.webp" alt="Spreading secrets" width="532" height="461" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
</ol>
<h3 id="setting-up-an-access-token"><a class="anchor-link" href="#setting-up-an-access-token">Setting up an access token</a></h3>
We also need to create an access token to be able to retrieve the secrets from the project.
<ol>
<li>
On the Doppler dashboard, select the project and click on "Access", then click on "Generate":
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rpko.webp" alt="Generate access token" width="770" height="343" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Then enter with a name for the access token and click on "Generate", then copy the access token.
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rqbu.webp" alt="Enter name for access token" width="946" height="562" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
<blockquote>
For security reasons, it's recommended to scope the access token for read-only.
</blockquote>
</li>
<li>
For now, save the access token in a secure place. We'll need it later.
</li>
</ol>
<h2 id="prefect"><a class="anchor-link" href="#prefect">Prefect</a></h2>
Prefect is a workflow management tool that allows you to manage workflows in a pythonic and reliable way. I'd recommend to check the <a href="https://docs.prefect.io/v3/getting-started/overview/">official documentation</a> for more information.
For simplicity, I'll assume you already have a Prefect project set up.
<h3 id="prefect-blocks"><a class="anchor-link" href="#prefect-blocks">Prefect blocks</a></h3>
Prefect blocks are a persistence mechanism for configuration and credentials, including secrets.
It gets the job done but for this example, we want to delegate the secrets management to Doppler.
In order to do that, let's create a new block called <code>doppler-config</code> to store the Doppler configuration.
In the Prefect UI, let's access the blocks section:
<ol>
<li>
First click on "Settings" on the sidebar:
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rfqx.webp" alt="Creating a new block" width="321" height="394" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Then click on "Blocks":
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rjgd.webp" alt="Blocks section" width="386" height="244" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Then click on "Block +"
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rjvj.webp" alt="Create block" width="260" height="48" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Then search for "Secret"
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rjys.webp" alt="Search for &#x22;Secret&#x22;" width="222" height="56" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Then click on "Secret"
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rlbc.webp" alt="Secret block" width="725" height="288" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
</li>
<li>
Now we need to fill the form with the following information:
<ul>
<li>
Name: <code>doppler-config</code>
</li>
<li>
Type: <code>JSON</code>
</li>
<li>
Value:
<pre><code class="hljs language-json">{
 "project": "my-project",
 "config": "dev",
 "access_token": "sv.*********************"
}
</code></pre>
Remember to replace the <code>access_token</code> with the one you copied earlier.
</li>
</ul>
<img src="/posts/a-better-way-to-manage-secrets-in-prefect-using-doppler/SCR-20251222-rmib.webp" alt="Fill the form" width="1075" height="512" loading="lazy" decoding="async" sizes="(max-width: 800px) 100vw, 800px">
Then click on "Create"
</li>
</ol>
<h2 id="the-code"><a class="anchor-link" href="#the-code">The code</a></h2>
With the setup complete, let's look at the code.
<h3 id="requirements"><a class="anchor-link" href="#requirements">Requirements</a></h3>
Before diving into the code, we'll need to have a few things in place:
<ul>
<li>Python 3.10+ installed</li>
<li><code>uv</code> or <code>pip</code> to install the dependencies</li>
</ul>
<blockquote>
Note: While using <code>pip</code> it's recommended to use a virtual environment to avoid conflicts with other projects.
<pre><code class="hljs language-bash">python -m venv .venv
source .venv/bin/activate
</code></pre>
</blockquote>
Install the dependencies:
<pre><code class="hljs language-bash"># Using uv
uv add doppler-sdk prefect python-dotenv pydantic pydantic-settings

# Using pip
pip install doppler-sdk prefect python-dotenv pydantic pydantic-settings
</code></pre>
<h2 id="whispering-our-secrets-to-prefect"><a class="anchor-link" href="#whispering-our-secrets-to-prefect">Whispering our secrets to Prefect</a></h2>
First things first, let's create a <code>src/settings.py</code> file to load our configuration from environment variables.
<pre><code class="hljs language-python"># src/settings.py

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
 secret_api_key: str

</code></pre>
Now we can define the function that brings our secrets to life.
<pre><code class="hljs language-python"># src/settings.py

from io import StringIO

from dopplersdk import DopplerSDK
from dotenv import load_dotenv
from prefect.blocks.system import Secret

def load_secrets_from_doppler():
 secret_block = Secret.load("doppler-config")
 doppler_config = secret_block.get()
 doppler = DopplerSDK(access_token=doppler_config["access_token"])
 response = doppler.secrets.download(
 config=doppler_config["config"],
 project=doppler_config["project"],
 format="env",
 )
 stream = StringIO(response.text)
 load_dotenv(stream=stream)
</code></pre>
This function performs the following steps:
<ol>
<li>
First, we load the secret block from Prefect and get the configuration.
<pre><code class="hljs language-python">secret_block = Secret.load("doppler-config")
doppler_config = secret_block.get()
</code></pre>
</li>
<li>
Then we initialize the Doppler SDK with the access token.
<pre><code class="hljs language-python">doppler = DopplerSDK(access_token=doppler_config["access_token"])
</code></pre>
</li>
<li>
Then we download the secrets from Doppler with <code>.env</code> format and save it in a string buffer.
<pre><code class="hljs language-python">response = doppler.secrets.download(
 config=doppler_config["config"],
 project=doppler_config["project"],
 format="env",
)
stream = StringIO(response.text)
</code></pre>
</li>
<li>
Finally we load the environment variables from the string buffer.
<pre><code class="hljs language-python">load_dotenv(stream=stream)
</code></pre>
</li>
</ol>
Until now, we have the secrets loaded into the environment variables. Let's see how to use them in our flow.
<h3 id="loading-the-secrets-in-our-flow"><a class="anchor-link" href="#loading-the-secrets-in-our-flow">Loading the secrets in our flow</a></h3>
Now we can load the secrets in our flow.
<pre><code class="hljs language-python"># src/my_flow.py

from prefect import flow

from .settings import Settings, load_secrets_from_doppler


@flow
def my_flow():
 load_secrets_from_doppler()
 settings = Settings()
 print(settings.secret_api_key)


if __name__ == "__main__":
 my_flow()
</code></pre>
<ol>
<li>
First we load the the secrets from Doppler into the environment variables.
<pre><code class="hljs language-python">load_secrets_from_doppler()
</code></pre>
</li>
<li>
Then we load the settings from the environment variables using the <code>Settings</code> class.
<pre><code class="hljs language-python">settings = Settings()
</code></pre>
It's mandatory to load the secrets into environment variables before instantiating the <code>Settings</code> class.
</li>
<li>
Finally we print the secret API key using the <code>settings</code> object.
<pre><code class="hljs language-python">print(settings.secret_api_key)
</code></pre>
</li>
</ol>
Now let's run the flow.
<pre><code class="hljs language-bash"># Using uv
uv run python src/my_flow.py

# Using pip with virtual environment
python src/my_flow.py
</code></pre>
We should see the secret API key printed in the console:
<pre><code class="hljs language-text">prefect.engine - View at https://app.prefect.cloud/account/24a1d5dd-fc9f-4a8e-a812-42e5648ba921/workspace/5495293d-ab61-4b84-9ad7-84c2d203ce73/runs/flow-run/06949dca-954e-7189-8000-d8b048e75ad8
Flow run 'amaranth-caterpillar' - Beginning flow run 'amaranth-caterpillar' for flow 'my-flow'
Flow run 'amaranth-caterpillar' - View at https://app.prefect.cloud/account/24a1d5dd-fc9f-4a8e-a812-42e5648ba921/workspace/5495293d-ab61-4b84-9ad7-84c2d203ce73/runs/flow-run/06949dca-954e-7189-8000-d8b048e75ad8
1234567890
Flow run 'amaranth-caterpillar' - Finished in state Completed()
</code></pre>
That's it! We have the secrets loaded into the environment variables and we can use them in our flow.
<blockquote>
Note that even we are running the flow locally, if the prefect profile is set to run in the cloud, the flow will load the block from the cloud.
</blockquote>
<h2 id="conclusion"><a class="anchor-link" href="#conclusion">Conclusion</a></h2>
In this post, we explored how to use Doppler to manage secrets in Prefect by centralizing secret management outside the orchestration layer. We used a single Prefect Secret block only to store Doppler configuration, while delegating all actual secret management to Doppler and exposing secrets to the application via environment variables.
Although this approach does not completely eliminate the use of Prefect Secret blocks, it reduces them to a single, stable integration point. In return, Doppler provides significantly more flexibility, control, and scalability for managing secrets, especially as a project grows to medium or large size.
The complete and runnable example of the code used in this post is available on Github: <a href="https://github.com/jonatasleon/prefect-doppler-config">https://github.com/jonatasleon/prefect-doppler-config</a>.
I hope you found this post helpful. If you have any questions, feel free to reach out to me on <a href="https://www.linkedin.com/in/jonatasleon/">LinkedIn</a>.

A Better Way to Manage Secrets in Prefect Using Doppler

Hello and welcome to my personal blog! This is where I'll be sharing my thoughts, experiences, and learnings.
<h2 id="what-to-expect"><a class="anchor-link" href="#what-to-expect">What to Expect</a></h2>
In this blog, you'll find:
<ul>
<li>Technical articles about web development, programming, and technology</li>
<li>Personal reflections on my journey as a developer</li>
<li>Tutorials and guides that I've found helpful</li>
<li>Project updates and behind-the-scenes content</li>
</ul>
<h2 id="getting-started"><a class="anchor-link" href="#getting-started">Getting Started</a></h2>
If you're reading this, you've successfully set up your blog! To create new posts:
<ol>
<li>Create a new <code>.md</code> file in the <code>posts/</code> directory</li>
<li>Add frontmatter with <code>title</code>, <code>date</code>, and optionally <code>excerpt</code></li>
<li>Write your content in Markdown</li>
<li>Push to GitHub and the blog will automatically deploy</li>
</ol>
<h2 id="markdown-support"><a class="anchor-link" href="#markdown-support">Markdown Support</a></h2>
This blog supports full Markdown syntax including:
<ul>
<li>Bold and italic text</li>
<li>Code blocks with syntax highlighting</li>
<li>Lists and links</li>
<li>Images and more!</li>
<li>LaTeX math equations - both inline and block format</li>
</ul>
Here's a code example:
<pre><code class="hljs language-javascript">function greet(name) {
 return `Hello, ${name}!`;
}

console.log(greet('World'));
</code></pre>
<h2 id="math-equations"><a class="anchor-link" href="#math-equations">Math Equations</a></h2>
This blog also supports LaTeX math equations! You can use inline math like <math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>E</mi><mo>=</mo><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup></mrow><annotation encoding="application/x-tex">E = mc^2</annotation></semantics></math>E=mc2 or display block equations:
<math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>P</mi><mo stretchy="false">(</mo><mi>A</mi><mi mathvariant="normal">∣</mi><mi>B</mi><mo stretchy="false">)</mo><mo>=</mo><mfrac><mrow><mi>P</mi><mo stretchy="false">(</mo><mi>B</mi><mi mathvariant="normal">∣</mi><mi>A</mi><mo stretchy="false">)</mo><mo>⋅</mo><mi>P</mi><mo stretchy="false">(</mo><mi>A</mi><mo stretchy="false">)</mo></mrow><mrow><mi>P</mi><mo stretchy="false">(</mo><mi>B</mi><mo stretchy="false">)</mo></mrow></mfrac></mrow><annotation encoding="application/x-tex">P(A|B) = \frac{P(B|A) \cdot P(A)}{P(B)}</annotation></semantics></math>P(A∣B)=P(B)P(B∣A)⋅P(A)​
This is Bayes' theorem, which is fundamental in probability theory. You can write any mathematical expression using LaTeX syntax!
Thanks for reading, and stay tuned for more content!

Jonatas Leon

Latest Posts

A Better Way to Manage Secrets in Prefect Using Doppler

Welcome to My Blog

Math Equations Example