From ca72ee30c3fc1094ca6106be0a139209098c8e75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Hanu=C5=A1?= <dh.david.hanus@gmail.com>
Date: Sun, 5 Jul 2026 13:59:02 +0200
Subject: [PATCH] =?UTF-8?q?docs(apify-actor-development):=20clarify=20`api?=
 =?UTF-8?q?fy=20push`=20builds=20but=20does=20not=20run=20=E2=80=94=20trig?=
 =?UTF-8?q?ger=20a=20run=20explicitly?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 skills/apify-actor-development/SKILL.md | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/skills/apify-actor-development/SKILL.md b/skills/apify-actor-development/SKILL.md
index ce02412..ebe829b 100644
--- a/skills/apify-actor-development/SKILL.md
+++ b/skills/apify-actor-development/SKILL.md
@@ -75,6 +75,7 @@ Use the appropriate CLI command based on the user's language choice. Additional
 6. **Write documentation** - Create comprehensive README.md for the marketplace (see [references/actor-readme.md](references/actor-readme.md) — this is mandatory, not optional)
 7. **Test locally** - Run `apify run` to verify functionality (see Local testing section below)
 8. **Deploy** - Run `apify push` to deploy the Actor on the Apify platform (Actor name is defined in `.actor/actor.json`)
+9. **Trigger a run** - `apify push` only builds; it does not execute the Actor. If the task is "deploy and produce output", follow up with `apify call <actor-id>` (blocking) or `apify actors start <actor-id> --input '{...}'` then `apify runs wait <runId>` (non-blocking). Confirm `apify runs info <runId>` reports `status: SUCCEEDED`. See [`apify push` builds, it does not run](#apify-push-builds-it-does-not-run) below.
 
 ## Security
 
@@ -180,6 +181,16 @@ Actor input is one JSON object, not an array. `--input` accepts inline JSON obje
 
 If no dedicated Actor exists for your target, search Apify Store for community options before building from scratch.
 
+### `apify push` builds, it does not run
+
+`apify push` only uploads source and builds a new Actor version — it does not execute the Actor. If the task is "deploy and produce output", follow up with an explicit invocation:
+
+- `apify call <actor-id>` — blocking, prints the run summary.
+- `apify actors start <actor-id> --input '{...}'` then `apify runs wait <runId>` — non-blocking start plus wait.
+- For Standby Actors: hit the Standby URL once so the platform spins up a run.
+
+End every deploy workflow with a check that `apify runs info <runId>` reports `status: SUCCEEDED`. A successful `apify push` exits 0 and prints a Console URL, which is easy to read as "done" even when the runs tab is still empty.
+
 ### Local and runtime commands
 
 Always use `apify run` to test Actors locally. Do not use `npm run start`, `npm start`, `yarn start`, or other package manager commands - these will not properly configure the Apify environment and storage.