From fa56a6b7b29d60874885678230a9193cc4911794 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 09:47:08 +0000 Subject: [PATCH 1/7] ci: review pull requests against the platform repositories `.github/review-references.yaml` names apify-core, apify-worker and apify-containerd-proxy as the repositories the apify-factory review compares a pull request with, and what to compare, drawn from the platform parity review's instructions. The stub calls the public reusable workflow directly, pinned to the ai-developer branch that drafts the feature, to compare the two reviews side by side. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/review-references.yaml | 67 +++++++++++++++++++++++++++ .github/workflows/factory_review.yaml | 13 ++++-- 2 files changed, 77 insertions(+), 3 deletions(-) create mode 100644 .github/review-references.yaml diff --git a/.github/review-references.yaml b/.github/review-references.yaml new file mode 100644 index 0000000..d1977f1 --- /dev/null +++ b/.github/review-references.yaml @@ -0,0 +1,67 @@ +# Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`). +# The runtime emulates the Apify platform, so a pull request here is reviewed against the platform's +# own code: the reviewer gets these repositories as source trees next to the pull request and +# compares. Read from the default branch, never from the pull request; gathered only for a pull +# request by a human member of the organization, on a branch of this repository. +version: 1 + +instructions: | + This repository emulates the Apify platform for local Actor development. Find where the pull + request makes the runtime behave differently from the real platform in a way a user would notice, + and report it when the requirements do not already admit it. Only what a user can observe counts: + status codes, error types and messages, field names and types, defaults, ordering, pagination, + limits, run and build lifecycle, events, and what an Actor sees in its container. Before reporting + a difference, search `requirements/` for a statement covering it: `unsupported.md` (behaviour not + emulated at all), the `501` list in `api.md`, and the "Known differences" sections such as the one + in `storage.md`. A documented difference is not a finding; one that is not documented, or is + documented the opposite way, is. Back every finding with the reference file and line. + +references: + - repository: apify/apify-core + ref: latest-release + paths: + - src/api/** + - src/packages/** + - src/daemons/** + instructions: | + The real platform: the API, storages, runs, builds, webhooks, schedules. Entry points: the + route handlers under `src/api/src/routes//` (actor_runs, actor_builds, actors, + actor_tasks, datasets, key_value_stores, request_queues, webhooks, logs, users, store), the + request and response shapes next to them, shared constants and limits in + `src/packages/consts/`, error types in `src/packages/errors/`, schemas in `src/packages/schemas/` + and the Actor-side behaviour in `src/packages/actor/` and `src/packages/actor-server/`. Compare + the endpoint the pull request implements or changes with its handler here: status codes, error + types and messages, field names and types, defaults, ordering, pagination and limits. + when: + - src/api/** + - src/storage/** + - src/services/** + - src/console/** + - requirements/** + + - repository: apify/apify-worker + instructions: | + How the platform starts a run's container: the environment variables an Actor sees, the + resources and limits it is given, its lifecycle, events, timeouts and how it is stopped. + Entry points: `src/runtime/` (the container runtimes, Docker and containerd), `src/actor/` + (the run's preparation and lifecycle), `src/builds/` (how an image is built), `src/consts/` and + `src/config/`. Compare what the runtime's driver and build do with what the worker does. + when: + - src/driver/** + - src/api/** + - src/services/** + - docker/** + - Dockerfile + - requirements/** + + - repository: apify/apify-containerd-proxy + instructions: | + How the platform routes and proxies traffic to and from a run's container (Go, under + `internal/`): the container's web server and Standby, request and response handling, headers, + timeouts and limits. Compare the runtime's container, HTTP and Standby proxies with it. + when: + - src/api/container-proxy.ts + - src/api/http-proxy.ts + - src/api/standby-proxy.ts + - src/services/** + - requirements/** diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml index 7d69beb..63f53da 100644 --- a/.github/workflows/factory_review.yaml +++ b/.github/workflows/factory_review.yaml @@ -1,7 +1,11 @@ name: apify-factory review (AI review, and auto-approval) -# Calls the review and auto-approval pipeline in apify/ai-developer. Approvals additionally need the -# repository's `factory_auto_approve` custom property set to true. +# Calls the review and auto-approval pipeline in apify/ai-developer, through the public reusable +# workflow in apify/workflows. Approvals additionally need the repository's `factory_auto_approve` +# custom property set to true. +# +# `.github/review-references.yaml` names the platform repositories the reviewer compares a pull +# request with; it is read from the base branch by the pipeline, nothing here has to pass it. on: # Taken from the default branch, never from the pull request, so a pull request cannot rewrite # its own review pipeline. Pull request code is never checked out or executed. @@ -19,11 +23,14 @@ permissions: jobs: factory-review: - uses: apify/ai-developer/.github/workflows/_factory_review.yaml@main + uses: apify/workflows/.github/workflows/factory_review.yaml@main secrets: inherit # Paths never auto-approved here, on top of the pipeline's defaults. Proposed from the # repository's layout when this workflow was added; edit them like any other code. with: + # The draft of the cross-repository references, to compare with the platform parity + # review. Back to `main` once it lands there. + ai-developer-ref: claude/ecstatic-euler-ki5zev policy: | { "denyGlobs": [ From 7a8e88caf1fbb356726dc06c2c46f50326857283 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 10:35:06 +0000 Subject: [PATCH 2/7] ci: gather every platform reference on every review Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/review-references.yaml | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/.github/review-references.yaml b/.github/review-references.yaml index d1977f1..60b80e8 100644 --- a/.github/review-references.yaml +++ b/.github/review-references.yaml @@ -32,12 +32,6 @@ references: and the Actor-side behaviour in `src/packages/actor/` and `src/packages/actor-server/`. Compare the endpoint the pull request implements or changes with its handler here: status codes, error types and messages, field names and types, defaults, ordering, pagination and limits. - when: - - src/api/** - - src/storage/** - - src/services/** - - src/console/** - - requirements/** - repository: apify/apify-worker instructions: | @@ -46,22 +40,9 @@ references: Entry points: `src/runtime/` (the container runtimes, Docker and containerd), `src/actor/` (the run's preparation and lifecycle), `src/builds/` (how an image is built), `src/consts/` and `src/config/`. Compare what the runtime's driver and build do with what the worker does. - when: - - src/driver/** - - src/api/** - - src/services/** - - docker/** - - Dockerfile - - requirements/** - repository: apify/apify-containerd-proxy instructions: | How the platform routes and proxies traffic to and from a run's container (Go, under `internal/`): the container's web server and Standby, request and response handling, headers, timeouts and limits. Compare the runtime's container, HTTP and Standby proxies with it. - when: - - src/api/container-proxy.ts - - src/api/http-proxy.ts - - src/api/standby-proxy.ts - - src/services/** - - requirements/** From ad8b7722efdfe41a8d75a99141668c04f5e65605 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 10:38:37 +0000 Subject: [PATCH 3/7] ci: follow the renamed ai-developer branch Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/workflows/factory_review.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml index 63f53da..e7b75ac 100644 --- a/.github/workflows/factory_review.yaml +++ b/.github/workflows/factory_review.yaml @@ -30,7 +30,7 @@ jobs: with: # The draft of the cross-repository references, to compare with the platform parity # review. Back to `main` once it lands there. - ai-developer-ref: claude/ecstatic-euler-ki5zev + ai-developer-ref: claude/review-references policy: | { "denyGlobs": [ From b85bcf09d5650dbeb8702c5648cc75528f01d175 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 14:53:30 +0000 Subject: [PATCH 4/7] ci: replace the platform parity review with the apify-factory review The apify-factory review now compares a pull request with apify-core, apify-worker and apify-containerd-proxy through `.github/review-references.yaml`, so the separate platform parity workflow and its Managed Agent session are no longer needed. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/workflows/factory_review.yaml | 4 +- .github/workflows/platform_parity_review.yaml | 75 ------------------- 2 files changed, 2 insertions(+), 77 deletions(-) delete mode 100644 .github/workflows/platform_parity_review.yaml diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml index e7b75ac..0bcc495 100644 --- a/.github/workflows/factory_review.yaml +++ b/.github/workflows/factory_review.yaml @@ -28,8 +28,8 @@ jobs: # Paths never auto-approved here, on top of the pipeline's defaults. Proposed from the # repository's layout when this workflow was added; edit them like any other code. with: - # The draft of the cross-repository references, to compare with the platform parity - # review. Back to `main` once it lands there. + # The cross-repository references are drafted on this ai-developer branch; back to + # `main` once they land there. ai-developer-ref: claude/review-references policy: | { diff --git a/.github/workflows/platform_parity_review.yaml b/.github/workflows/platform_parity_review.yaml deleted file mode 100644 index ab7777f..0000000 --- a/.github/workflows/platform_parity_review.yaml +++ /dev/null @@ -1,75 +0,0 @@ -# Hands a pull request to the Actor Runtime Review Managed Agent. The agent is defined in -# apify/apify-tooling-orchestration (`automations/actor-runtime-review/`); it compares the pull request with how the -# real Apify platform behaves and posts its comment itself. -# -# One session per pull request: `apify-agents send` finds the agent's session carrying this pull request's -# metadata, or starts it, and delivers every push behind an interrupt, so a review of an older commit is never -# finished, let alone posted. The agent re-reads the head before posting, so a push this workflow does not run for -# (paths outside the filter) still never gets a stale comment. Closing or merging the pull request archives its -# session with `apify-agents archive`. -name: Platform parity review - -on: - pull_request: - types: [opened, synchronize, ready_for_review, closed] - paths: - - src/** - - docker/** - - Dockerfile - - requirements/** - - skills/** - -permissions: - contents: read - -# One run per pull request at a time, and of the runs waiting behind it only the newest survives, so pushes reach -# the session in order and a push that is already superseded is not sent at all. -concurrency: - group: platform-parity-review-${{ github.event.pull_request.number }} - cancel-in-progress: false - -jobs: - session: - name: ${{ github.event.action == 'closed' && 'Archive the review session' || 'Send the pull request to its review session' }} - runs-on: ubuntu-latest - # Secrets are not available to PRs from forks. A draft is not reviewed, but closing one still archives. - if: >- - github.event.pull_request.head.repo.full_name == github.repository - && (github.event.action == 'closed' || !github.event.pull_request.draft) - env: - ANTHROPIC_API_KEY: ${{ secrets.ACTOR_RUNTIME_REVIEW_KEY }} - AGENT_DIR: automations/actor-runtime-review/agents - REPOSITORY: ${{ github.repository }} - PR_NUMBER: ${{ github.event.pull_request.number }} - PR_CREATED_AT: ${{ github.event.pull_request.created_at }} - - steps: - # The tooling and the agent's ids live in apify/apify-tooling-orchestration. It is an internal repository, - # which a public one can neither call reusable workflows from nor read with its own token. - - uses: actions/checkout@v4 - with: - repository: apify/apify-tooling-orchestration - ref: master - token: ${{ secrets.APIFY_SERVICE_ACCOUNT_GITHUB_TOKEN }} - - uses: astral-sh/setup-uv@v7 - - run: uv sync --all-packages - - - name: Send the push to the pull request's session - if: github.event.action != 'closed' - env: - PR_URL: ${{ github.event.pull_request.html_url }} - HEAD_SHA: ${{ github.event.pull_request.head.sha }} - run: | - uv run apify-agents send "$AGENT_DIR" \ - --metadata "repository=$REPOSITORY" --metadata "pull_request=$PR_NUMBER" \ - --created-after "$PR_CREATED_AT" --title "PR #$PR_NUMBER" \ - --message "Review this pull request: $PR_URL (head commit $HEAD_SHA)." \ - | tee -a "$GITHUB_STEP_SUMMARY" - - - name: Archive the pull request's session - if: github.event.action == 'closed' - run: | - uv run apify-agents archive "$AGENT_DIR" \ - --metadata "repository=$REPOSITORY" --metadata "pull_request=$PR_NUMBER" \ - --created-after "$PR_CREATED_AT" \ - | tee -a "$GITHUB_STEP_SUMMARY" From 3a1d2d2cbd2206fd864b02104710e9eb93d3f268 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 15:06:15 +0000 Subject: [PATCH 5/7] ci: point the Claude instructions at the review references Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/review-references.yaml | 46 +++++++++++----------------------- CLAUDE.MD | 5 ++++ 2 files changed, 20 insertions(+), 31 deletions(-) diff --git a/.github/review-references.yaml b/.github/review-references.yaml index 60b80e8..464e7f5 100644 --- a/.github/review-references.yaml +++ b/.github/review-references.yaml @@ -1,20 +1,14 @@ # Cross-repository references for the apify-factory review (apify/ai-developer, `review-references`). -# The runtime emulates the Apify platform, so a pull request here is reviewed against the platform's -# own code: the reviewer gets these repositories as source trees next to the pull request and -# compares. Read from the default branch, never from the pull request; gathered only for a pull -# request by a human member of the organization, on a branch of this repository. version: 1 instructions: | - This repository emulates the Apify platform for local Actor development. Find where the pull - request makes the runtime behave differently from the real platform in a way a user would notice, - and report it when the requirements do not already admit it. Only what a user can observe counts: - status codes, error types and messages, field names and types, defaults, ordering, pagination, - limits, run and build lifecycle, events, and what an Actor sees in its container. Before reporting - a difference, search `requirements/` for a statement covering it: `unsupported.md` (behaviour not - emulated at all), the `501` list in `api.md`, and the "Known differences" sections such as the one - in `storage.md`. A documented difference is not a finding; one that is not documented, or is - documented the opposite way, is. Back every finding with the reference file and line. + This repository emulates the Apify platform for local Actor development. Find where the pull request + makes the runtime behave differently from the real platform in a way a user would notice: status + codes, error types and messages, field names and types, defaults, ordering, pagination, limits, run + and build lifecycle, events, and what an Actor sees in its container. A difference documented in + `requirements/` (`unsupported.md`, the `501` list in `api.md`, the "Known differences" sections) is + not a finding. Back every finding with the reference file and line (create public github link fixed + to a commit you have seen). references: - repository: apify/apify-core @@ -24,25 +18,15 @@ references: - src/packages/** - src/daemons/** instructions: | - The real platform: the API, storages, runs, builds, webhooks, schedules. Entry points: the - route handlers under `src/api/src/routes//` (actor_runs, actor_builds, actors, - actor_tasks, datasets, key_value_stores, request_queues, webhooks, logs, users, store), the - request and response shapes next to them, shared constants and limits in - `src/packages/consts/`, error types in `src/packages/errors/`, schemas in `src/packages/schemas/` - and the Actor-side behaviour in `src/packages/actor/` and `src/packages/actor-server/`. Compare - the endpoint the pull request implements or changes with its handler here: status codes, error - types and messages, field names and types, defaults, ordering, pagination and limits. - + The real platform: the API, storages, runs, builds, webhooks, schedules. Route handlers live under + `src/api/src/routes//`, constants and limits in `src/packages/consts/`. Compare the + endpoint the pull request implements or changes with its handler here. - repository: apify/apify-worker instructions: | - How the platform starts a run's container: the environment variables an Actor sees, the - resources and limits it is given, its lifecycle, events, timeouts and how it is stopped. - Entry points: `src/runtime/` (the container runtimes, Docker and containerd), `src/actor/` - (the run's preparation and lifecycle), `src/builds/` (how an image is built), `src/consts/` and - `src/config/`. Compare what the runtime's driver and build do with what the worker does. - + How the platform starts a run's container: environment variables, resources and limits, lifecycle, + events and timeouts (`src/runtime/`, `src/actor/`, `src/builds/`). Compare the runtime's driver + and build with it. - repository: apify/apify-containerd-proxy instructions: | - How the platform routes and proxies traffic to and from a run's container (Go, under - `internal/`): the container's web server and Standby, request and response handling, headers, - timeouts and limits. Compare the runtime's container, HTTP and Standby proxies with it. + How the platform routes and proxies traffic to and from a run's container (`internal/`). Compare + the runtime's container, HTTP and Standby proxies with it. diff --git a/CLAUDE.MD b/CLAUDE.MD index 52e022b..66fc59c 100644 --- a/CLAUDE.MD +++ b/CLAUDE.MD @@ -34,6 +34,11 @@ does not emulate). When a change alters what the runtime does for its users, update `skills/actor-runtime/SKILL.md` in the same commit - it is shipped documentation, not a README. +### Additional context + +The runtime emulates code that lives in other repositories. The most important references are defined in +[review references](./.github/review-references.yaml). + ## Contribution conventions ### Requirements (`requirements/*.md`) From 3107a96784c673cb253f5d36da563e2cb8b015fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Josef=20Proch=C3=A1zka?= Date: Tue, 3 Nov 2026 16:32:10 +0100 Subject: [PATCH 6/7] Clean up comments in factory_review.yaml Removed comments explaining the workflow setup and behavior. --- .github/workflows/factory_review.yaml | 6 ------ 1 file changed, 6 deletions(-) diff --git a/.github/workflows/factory_review.yaml b/.github/workflows/factory_review.yaml index 0bcc495..1262e9e 100644 --- a/.github/workflows/factory_review.yaml +++ b/.github/workflows/factory_review.yaml @@ -1,11 +1,5 @@ name: apify-factory review (AI review, and auto-approval) -# Calls the review and auto-approval pipeline in apify/ai-developer, through the public reusable -# workflow in apify/workflows. Approvals additionally need the repository's `factory_auto_approve` -# custom property set to true. -# -# `.github/review-references.yaml` names the platform repositories the reviewer compares a pull -# request with; it is read from the base branch by the pipeline, nothing here has to pass it. on: # Taken from the default branch, never from the pull request, so a pull request cannot rewrite # its own review pipeline. Pull request code is never checked out or executed. From a6ce0c9c9538987e1c99db0df035a83b71594498 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 3 Nov 2026 15:48:33 +0000 Subject: [PATCH 7/7] style: format the review references with Prettier Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_017ocuAL43YR6VPaBRrRfBbL --- .github/review-references.yaml | 52 +++++++++++++++++----------------- 1 file changed, 26 insertions(+), 26 deletions(-) diff --git a/.github/review-references.yaml b/.github/review-references.yaml index 464e7f5..b95c50d 100644 --- a/.github/review-references.yaml +++ b/.github/review-references.yaml @@ -2,31 +2,31 @@ version: 1 instructions: | - This repository emulates the Apify platform for local Actor development. Find where the pull request - makes the runtime behave differently from the real platform in a way a user would notice: status - codes, error types and messages, field names and types, defaults, ordering, pagination, limits, run - and build lifecycle, events, and what an Actor sees in its container. A difference documented in - `requirements/` (`unsupported.md`, the `501` list in `api.md`, the "Known differences" sections) is - not a finding. Back every finding with the reference file and line (create public github link fixed - to a commit you have seen). + This repository emulates the Apify platform for local Actor development. Find where the pull request + makes the runtime behave differently from the real platform in a way a user would notice: status + codes, error types and messages, field names and types, defaults, ordering, pagination, limits, run + and build lifecycle, events, and what an Actor sees in its container. A difference documented in + `requirements/` (`unsupported.md`, the `501` list in `api.md`, the "Known differences" sections) is + not a finding. Back every finding with the reference file and line (create public github link fixed + to a commit you have seen). references: - - repository: apify/apify-core - ref: latest-release - paths: - - src/api/** - - src/packages/** - - src/daemons/** - instructions: | - The real platform: the API, storages, runs, builds, webhooks, schedules. Route handlers live under - `src/api/src/routes//`, constants and limits in `src/packages/consts/`. Compare the - endpoint the pull request implements or changes with its handler here. - - repository: apify/apify-worker - instructions: | - How the platform starts a run's container: environment variables, resources and limits, lifecycle, - events and timeouts (`src/runtime/`, `src/actor/`, `src/builds/`). Compare the runtime's driver - and build with it. - - repository: apify/apify-containerd-proxy - instructions: | - How the platform routes and proxies traffic to and from a run's container (`internal/`). Compare - the runtime's container, HTTP and Standby proxies with it. + - repository: apify/apify-core + ref: latest-release + paths: + - src/api/** + - src/packages/** + - src/daemons/** + instructions: | + The real platform: the API, storages, runs, builds, webhooks, schedules. Route handlers live under + `src/api/src/routes//`, constants and limits in `src/packages/consts/`. Compare the + endpoint the pull request implements or changes with its handler here. + - repository: apify/apify-worker + instructions: | + How the platform starts a run's container: environment variables, resources and limits, lifecycle, + events and timeouts (`src/runtime/`, `src/actor/`, `src/builds/`). Compare the runtime's driver + and build with it. + - repository: apify/apify-containerd-proxy + instructions: | + How the platform routes and proxies traffic to and from a run's container (`internal/`). Compare + the runtime's container, HTTP and Standby proxies with it.