Great question! In Prefect 3.x you pull your flow code at runtime using the pull steps in prefect.yaml. Since you already created a BitBucket Repository block in Prefect Cloud, the simplest way is to reference it with the pull_with_block step. Here are two working options: 1) Use your BitBucketRepository block (recommended since you already created it) - Block type slug: bitbucket-repository - Use the block’s saved name as block_document_name Example prefect.yaml snippet:

pull:
  - prefect.deployments.steps.pull.pull_with_block:
      block_document_name: my-bitbucket-repo-block   # the name you gave the block
      block_type_slug: bitbucket-repository

deployments:
  - name: my-deployment
    entrypoint: flows/my_flow.py:my_flow            # adjust to your flow
    work_pool:
      name: my-work-pool

This tells Prefect to load your BitBucketRepository block and pull the repo as configured in the block (URL, branch, credentials, subdirectory, etc.). 2) Use git_clone with a BitBucketCredentials block If instead you have a BitBucketCredentials block and want to specify the repo URL in YAML:

pull:
  - prefect.deployments.steps.pull.git_clone:
      repository: "<https://bitbucket.org/<workspace>/<repo>.git>"
      branch: main
      credentials: "{{ prefect.blocks.bitbucket-credentials.my-bitbucket-creds }}"

Notes and gotchas: - Make sure the environment running your deployments (e.g., worker image) has the integration installed: - pip install prefect-bitbucket - Block slugs to use in YAML: - BitBucketRepository: bitbucket-repository - BitBucketCredentials: bitbucket-credentials - If your repo is private, put the token/app password in a BitBucketCredentials block and either attach it to your BitBucketRepository block (Option 1) or reference it via the credentials field (Option 2). - Your entrypoint should point to the flow file and function within the pulled repo. Docs for reference: - Pull steps (git_clone, pull_with_block): Pull steps API - prefect.yaml guide: Using prefect.yaml - Bitbucket integration: prefect-bitbucket If you share the exact name of your BitBucketRepository block and your flow’s entrypoint, I can draft a complete prefect.yaml tailored to your setup.

That error is coming from Git because the token is being embedded directly in the URL and it contains a “/”, which makes the URL invalid. You don’t want HTML escaping here — you need URL percent-encoding — or better yet, avoid putting the token in the URL at all. Recommended fixes (pick one): 1) Use your BitBucketRepository block via pull_with_block This avoids any URL construction and encoding issues:

pull:
  - prefect.deployments.steps.pull.pull_with_block:
      block_document_name: my-bitbucket-repo-block   # your block’s name
      block_type_slug: bitbucket-repository

deployments:
  - name: my-deployment
    entrypoint: flows/my_flow.py:my_flow

2) Use git_clone with a BitBucketCredentials block Pass credentials via a block instead of

access_token

so Prefect handles auth safely:

pull:
  - prefect.deployments.steps.pull.git_clone:
      repository: "<https://bitbucket.org/<workspace>/<repo>.git>"
      branch: main
      credentials: "{{ prefect.blocks.bitbucket-credentials.my-bitbucket-creds }}"

If you must keep using access_token - You’ll need to percent-encode the token before injecting it (e.g., replace “/” with “%2F”). You can store a pre-encoded token in a Secret block and reference that. But the two options above are safer and simpler. Notes: - Ensure your worker environment has the integration installed:

pip install prefect-bitbucket

- Block slugs: - BitBucketRepository: bitbucket-repository - BitBucketCredentials: bitbucket-credentials - Whether you need a username in the BitBucketCredentials block depends on your setup: - Many Bitbucket Cloud flows work with token-only OAuth; others (e.g., app passwords or Bitbucket Server) require username + token. The block handles the details; just provide what your Bitbucket setup requires. Docs: - Pull steps (git_clone, pull_with_block): Pull steps API - prefect.yaml guide: Using prefect.yaml - Bitbucket integration: prefect-bitbucket If you share your current prefect.yaml

pull:

section and whether you’re on Bitbucket Cloud or Server (and using OAuth token vs app password), I can suggest the exact edit.