prefect deploy should validate yaml file before deploying

[Ben-Epstein]

Bug summary

I was working through this guide https://docs.prefect.io/v3/deploy/infrastructure-concepts/prefect-yaml#the-pull-action and was struggling to set the set_working_directory step because it's not actually specified how to use it. I tried

pull:
- prefect.deployments.steps.git_clone:
    id: clone-step
    repository: https://github.com/Team/repo
    branch: main
    credentials: '{{ prefect.blocks.github-credentials.my-repo-pull }}'
    set_working_directory: '{{ clone-step.directory }}/my-app'

as well as

- prefect.deployments.steps.git_clone:
    id: clone-step
    repository: https://github.com/Team/repo
    branch: main
    credentials: '{{ prefect.blocks.github-credentials.my-repo-pull }}'
- set_working_directory:  '{{ clone-step.directory }}/my-app'

(which is what prefect docs AI said, but didn't make sense to me)

as well as a few others, until I searched for the usage of it in the repo to find the right syntax.

In each failed case, prefect was happy to let me deploy, but then failed when actually running the flow. This feels like it could be validated upfront to dramatically reduce my cycle time as a developer.

Version info

❯ uv run prefect version
Version:             3.1.15
API version:         0.8.4
Python version:      3.11.9
Git commit:          3ac3d548
Built:               Thu, Jan 30, 2025 11:31 AM
OS/Arch:             darwin/arm64
Profile:             ephemeral
Server type:         cloud
Pydantic version:    2.10.4
Integrations:
  prefect-github:    0.3.1

Additional context

No response

[Ben-Epstein]

just as another real-world use-case, i just accidentally did

- prefect.deployment.steps.set_working_directory:

instead of - prefect.deployments.steps.set_working_directory: (missing s) and again it deployed happily and then I got the confusing error message on running my flow ModuleNotFoundError: No module named 'prefect.deployment'

[zzstoatzz]

hi @Ben-Epstein - thanks for the issue! I agree there's more we could do on a couple fronts here:

• we should have better IDE support for prefect.yaml as outlined in Add prefect.yaml support deployment schema #16717
• we could do validation of build / push / pull steps up front as we could load the associated function (all steps are fully qualified function names) and check the provided values against their signatures

as for (what appears to be) your case though, is it possible you don't need set_working_directory here? if you're just trying to clone a remote repo, the git_clone step alone should suffice. set_working_directory is typically only needed if you're baking code into an image or if you have a process worker looking for source in a bunch of different places on the same machine

[Ben-Epstein]

thanks @zzstoatzz -- since we are chatting about the actual set_working_directory issue in slack, i'll leave that out from here.

Seems like you potentially have a matching issue in #16717, so if you think that encapsulates the issue better than this one then feel free to close :)