docs: Improve Actors environment variables docs #1668

patrikbraborec · 2025-07-03T20:51:21Z

The improvements address issues I encountered during building my first actor and setting env variables. Please take it as a suggestion open to discussion!
The page now contains some "duplicate" information with the page https://docs.apify.com/cli/docs/vars#set-up-environment-variables-in-apify-console. I think that is not an issue; maybe we can interlink those pages.
I am not completely sure about the Configuration class and how I described it, but I tried it locally and in Apify console, and it worked that way, but I just maybe do not understand it yet.

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

cursor

Bug: Misleading Variable Assignment in Python Example

In the Python example for accessing environment variables, the variable userId is misleadingly assigned the value of os.environ['api_token']. This contradicts the variable's name and the surrounding comments, causing confusion.

sources/platform/actors/development/programming_interface/environment_variables.md#L157-L161

apify-docs/sources/platform/actors/development/programming_interface/environment_variables.md

Lines 157 to 161 in ff39d10

    
           # get api_token 
        
           userId = os.environ['api_token'] 
        
           # print api_token to console 
        
           print(userId)

Fix in Cursor • Fix in Web

Comment bugbot run to trigger another review on this PR
Was this report helpful? Give feedback by reacting with 👍 or 👎

apify-service-account · 2025-07-03T20:54:47Z

Preview for this PR was built for commit ff39d100 and is ready at https://pr-1668.preview.docs.apify.com!

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

apify-service-account · 2025-07-03T21:02:07Z

Preview for this PR was built for commit f59a3f25 and is ready at https://pr-1668.preview.docs.apify.com!

apify-service-account · 2025-07-03T21:05:04Z

Preview for this PR was built for commit 6e113021 and is ready at https://pr-1668.preview.docs.apify.com!

TC-MO

Did few rewrites for clarity & conciseness
rewrote notes to be more active voice to adhere to msoft style guide and general technical writing principle

sources/platform/actors/development/programming_interface/environment_variables.md

apify-service-account · 2025-07-03T21:58:51Z

Preview for this PR was built for commit 1fe541de and is ready at https://pr-1668.preview.docs.apify.com!

sources/platform/actors/development/programming_interface/environment_variables.md

metalwarrior665 · 2025-07-04T06:57:50Z

sources/platform/actors/development/programming_interface/environment_variables.md

@@ -14,6 +14,21 @@ import TabItem from '@theme/TabItem';

 ---

+## How to use environment variables in Actors
+
+There are two ways how you can set up environment variables for Actors:


As I explain below, actor.json env vars only work with Apify CLI. So I think that was partially a reason why we didn't explain it much here, it might confuse users that use git integration (which is most serious users). So I would reword this a bit to make sure it is clear.

I added note to the Set up environment variables in actor.json section about the Git workflows.

sources/platform/actors/development/programming_interface/environment_variables.md

metalwarrior665 · 2025-07-04T07:03:24Z

sources/platform/actors/development/programming_interface/environment_variables.md

+:::info Build-time variables
+
+Custom environment variables are set during the Actor's build process and cannot be changed for existing builds. For more information, check out the [Builds](../builds_and_runs/builds.md) page.


This is confusing. Yes, it is true but Build-time variables resembles the Apply environment variables also to the build process option which we have next to env vars which is about injecting env vars to be available to the Dockerfile, not about needing to rebuild.

Sorry, I see you just copied existing text so then that's more on @TC-MO. Even if I check the current page, it is wrong, because the banner is unrelated to section below Build-time environment variables so I would just find a better name for :::info Build-time variables

would something like:

Variables set during the build

Build-specific environment variables

work better?

For the info note Variables set during the build is ok. I can think also of Variables bound to a build, Variables set to a specific build etc.

For the section Build-time environment variables sounds better than Build-specific environment variables (that suggests it is bound to a single build).

I changed the info note to Variables set during the build

sources/platform/actors/development/programming_interface/environment_variables.md

metalwarrior665 · 2025-07-04T07:09:51Z

sources/platform/actors/development/programming_interface/environment_variables.md

 ```

 </TabItem>
 </Tabs>

-## Use the `Configuration` class
+## Access system environment variables


Not sure why we recommend using Configuration @TC-MO ? For Apify injected env vars, it is better to use Actor.getEnv() which is fully typed with autocompletion. Configuration class is more general config file that you can use also for non-env settings (Cralwee also uses it for some scraping settings). So I would replace it completely, Configuration is only for very advanced users.

I checked history and the Configuration class was there since the beginning. I made it more prominent during one of the rewrites that aimed for one voice & tone throughout whole documentation. We can remove it completely if you think that this is an anti-pattern that we would not like to promote, or create a disclaimer/note that would warn users about dangers of using this approach

Oh I see now. What confused me that @patrikbraborec added it under Access system environment variables where we should use Actor.getEnv(). But in the original text, Configuration is mentioned on its own which is ok (although the use-case is quite niche)

The only reason to use Configuration instead of Actor.getEnv() is that it can set env vars (3rd way instead of Console or actor.json but it is the only programmatic way).

I would revert this change and update it in another PR. In there, I would mention Actor.getEnv in https://docs.apify.com/platform/actors/development/programming-interface/environment-variables#system-environment-variables and then just in Configuration note that it for reading env vars, users should prefer typed Actor.getEnv

What about removing the section completely, if the use case is quite niche?

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

apify-service-account · 2025-07-04T11:27:40Z

Preview for this PR was built for commit 27c720ab and is ready at https://pr-1668.preview.docs.apify.com!

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

apify-service-account · 2025-07-04T11:31:58Z

Preview for this PR was built for commit 2891771b and is ready at https://pr-1668.preview.docs.apify.com!

apify-service-account · 2025-07-04T11:34:44Z

Preview for this PR was built for commit c4cb588c and is ready at https://pr-1668.preview.docs.apify.com!

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

apify-service-account · 2025-07-04T12:01:08Z

Preview for this PR was built for commit f2aafda2 and is ready at https://pr-1668.preview.docs.apify.com!

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

apify-service-account · 2025-07-04T12:17:11Z

Preview for this PR was built for commit 05cc36c8 and is ready at https://pr-1668.preview.docs.apify.com!

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

apify-service-account · 2025-07-04T14:18:23Z

Preview for this PR was built for commit 3e83d6e3 and is ready at https://pr-1668.preview.docs.apify.com!

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

apify-service-account · 2025-07-04T14:21:11Z

Preview for this PR was built for commit 97fb2d09 and is ready at https://pr-1668.preview.docs.apify.com!

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

apify-service-account · 2025-07-04T14:23:53Z

Preview for this PR was built for commit 672168ec and is ready at https://pr-1668.preview.docs.apify.com!

apify-service-account · 2025-07-04T14:27:03Z

Preview for this PR was built for commit fa1a1f67 and is ready at https://pr-1668.preview.docs.apify.com!

docs: Improve Actors environment variables docs

ff39d10

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

patrikbraborec requested a review from TC-MO as a code owner July 3, 2025 20:51

cursor bot reviewed Jul 3, 2025

View reviewed changes

patrikbraborec added 2 commits July 3, 2025 22:58

chore: fix links in Actors environment docs

f59a3f2

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

docs: Change example in Actor environment docs

6e11302

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

TC-MO requested changes Jul 3, 2025

View reviewed changes

fix mdlint

1fe541d

metalwarrior665 requested changes Jul 4, 2025

View reviewed changes

Update sources/platform/actors/development/programming_interface/envi…

27c720a

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

patrikbraborec and others added 3 commits July 4, 2025 13:29

Update sources/platform/actors/development/programming_interface/envi…

25207f7

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/programming_interface/envi…

2891771

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/programming_interface/envi…

c4cb588

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/programming_interface/envi…

f2aafda

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

docs: Update env variables example

05cc36c

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

patrikbraborec and others added 2 commits July 4, 2025 16:14

docs: Add explanation of actor.json with git-workflow

3e83d6e

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

Update sources/platform/actors/development/programming_interface/envi…

97fb2d0

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

Update sources/platform/actors/development/programming_interface/envi…

672168e

…ronment_variables.md Co-authored-by: Michał Olender <92638966+TC-MO@users.noreply.github.com>

docs: Fix note section

fa1a1f6

Signed-off-by: Patrik Braborec <patrikbraborec@gmail.com>

patrikbraborec self-assigned this Jul 4, 2025

TC-MO added documentation Improvements or additions to documentation. adhoc Ad-hoc unplanned task added during the sprint. labels Jul 4, 2025

	# get api_token
	userId = os.environ['api_token']

	# print api_token to console
	print(userId)

		:::info Build-time variables

		Custom environment variables are set during the Actor's build process and cannot be changed for existing builds. For more information, check out the [Builds](../builds_and_runs/builds.md) page.

docs: Improve Actors environment variables docs #1668

Are you sure you want to change the base?

docs: Improve Actors environment variables docs #1668

Uh oh!

Conversation

patrikbraborec commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

Bug: Misleading Variable Assignment in Python Example

Uh oh!

apify-service-account commented Jul 3, 2025

Uh oh!

apify-service-account commented Jul 3, 2025

Uh oh!

apify-service-account commented Jul 3, 2025

Uh oh!

TC-MO left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apify-service-account commented Jul 3, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

metalwarrior665 Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

apify-service-account commented Jul 4, 2025

Uh oh!

Uh oh!

patrikbraborec commented Jul 3, 2025 •

edited

Loading

metalwarrior665 Jul 4, 2025 •

edited

Loading