Automate PR creation when OpenAPI spec is updated

[vdusek]

Context

As part of the effort to introduce fully typed & generated API clients (apify/apify-core#25186), the Python client will generate Pydantic models and type annotations from the OpenAPI specification (see #481).

Once the generation pipeline is in place, we need a mechanism to keep the generated code in sync with the OpenAPI spec automatically, so that changes to the API are promptly reflected in the client without manual intervention.

Goal

Set up a CI/CD automation (e.g. GitHub Actions workflow) that:

1. Detects changes to the OpenAPI specification (e.g. via a scheduled check, a webhook/dispatch from apify-docs, or by polling https://docs.apify.com/api/openapi.json).
2. Re-runs the code generation pipeline to produce updated models/types.
3. Opens a PR automatically in apify-client-python with the regenerated code, so it can be reviewed and merged.

Considerations

• The trigger mechanism needs to be decided — options include:
  • A repository_dispatch event sent from the apify-docs repo (or wherever the OpenAPI spec is maintained) whenever the spec changes.
  • A scheduled workflow (e.g. daily cron) that fetches the latest spec, compares it against the currently used version, and opens a PR if there are differences.
  • A webhook from the API deployment pipeline.
• The PR should include a clear diff of generated changes and ideally reference which OpenAPI spec version/commit triggered the update.
• Consider running linting, type checking, and tests as part of the PR to catch breaking changes early.
• Similar automation should likely be set up for apify-client-js as well (apify/apify-client-js#823).

Related

• Parent epic: apify/apify-core#25186
• Typed Python client: Introduce fully typed Python API client #481
• OpenAPI sync mechanism: apify/apify-core#22169