Which Cloudflare product(s) does this affect?
Pages, Wrangler
What version of Wrangler are you using?
Wrangler 4.108.0
What operating system are you using?
Windows
Describe the issue
There is a confusing mismatch between the Wrangler/API behavior, the public documentation, and the Dashboard workflow for Cloudflare Pages projects.
A Pages project was initially created via Direct Upload using Wrangler:
wrangler pages project create <project-name>
wrangler pages deploy <build-output-directory> --project-name <project-name> --branch main
Later, I wanted to connect the same Pages project to a GitHub repository for automatic deployments.
From the CLI, there does not appear to be a command for connecting an existing Pages project to a Git repository.
From the public API, attempting to update the source object of the existing Direct Upload project returns:
You cannot update the `source` object in a Direct Uploads project.
This message is technically understandable for the API path, but in practice it is misleading because the Cloudflare Dashboard appears to provide a non-destructive workflow for connecting a Git repository to the same Pages project. After using the Dashboard, the project showed Git Provider: Yes, and a production deployment was triggered from the Git commit.
Why this is confusing
The current API error strongly suggests that deleting and recreating the Pages project is the only path to Git integration.
That conclusion can lead users and automation tools to perform unnecessary destructive operations, even though the Dashboard may provide a supported manual workflow.
The current Wrangler CLI surface also does not make the distinction clear:
wrangler pages project list
wrangler pages project create
wrangler pages project delete
wrangler pages deploy
There is no visible command or output guidance that says something like:
This cannot be done via Wrangler/API, but you can connect a Git repository from the Dashboard.
Expected behavior
At minimum, the Wrangler/API error message or related documentation should distinguish between:
- What is unsupported through API/Wrangler
- What may be supported through the Dashboard
- What users should do if they need a fully automatable setup
For example, the error message could be clarified as:
Direct Upload Pages projects cannot update `source` via API/Wrangler.
To connect a Git repository, use the Cloudflare Dashboard:
Workers & Pages > your Pages project > Settings > Builds > Git Repository.
If you need to manage this fully through automation, create a new Git-integrated Pages project instead.
Or, if the Dashboard workflow is not intended to be supported, the Dashboard and documentation should be aligned so users are not presented with conflicting behavior.
Actual behavior
- Wrangler can create and deploy a Direct Upload Pages project.
- Wrangler does not expose a clear command to connect that project to a Git repository.
- The public API rejects updating the
source object.
- The error message does not mention the Dashboard path.
- The Dashboard appears to allow connecting a Git repository to the existing project.
- After using the Dashboard workflow, the project is reported as Git-backed and can deploy from Git commits.
Suggested improvement
Please clarify one of the following:
Option A: Dashboard Git binding for Direct Upload projects is supported
If this workflow is supported, please document it and mention it in Wrangler/API error output.
The error message should avoid implying that deletion/recreation is the only path.
Option B: Dashboard Git binding for Direct Upload projects is not intended to be supported
If this workflow is not intended to be supported, then the Dashboard, API, Wrangler, and docs should be aligned so users do not see contradictory behavior.
Option C: CLI/API support is planned
If Dashboard can do this safely, consider exposing the same workflow through Wrangler/API, or at least document that it is Dashboard-only.
Related issues / context
There are related issues around Pages Git integration and source management, but they do not seem to cover this exact mismatch in error guidance:
This issue is specifically about the misleading user experience when API/Wrangler says the source object cannot be updated, while the Dashboard appears to offer a viable Git repository binding path.
Impact
This affects both human users and automation tools.
When the API says the source object cannot be updated and no Dashboard path is mentioned, users may reasonably conclude that the project must be deleted and recreated. That is a destructive workaround and may cause unnecessary downtime or loss of deployment history.
A clearer message would prevent avoidable destructive actions.
Which Cloudflare product(s) does this affect?
Pages, Wrangler
What version of Wrangler are you using?
Wrangler 4.108.0
What operating system are you using?
Windows
Describe the issue
There is a confusing mismatch between the Wrangler/API behavior, the public documentation, and the Dashboard workflow for Cloudflare Pages projects.
A Pages project was initially created via Direct Upload using Wrangler:
Later, I wanted to connect the same Pages project to a GitHub repository for automatic deployments.
From the CLI, there does not appear to be a command for connecting an existing Pages project to a Git repository.
From the public API, attempting to update the
sourceobject of the existing Direct Upload project returns:This message is technically understandable for the API path, but in practice it is misleading because the Cloudflare Dashboard appears to provide a non-destructive workflow for connecting a Git repository to the same Pages project. After using the Dashboard, the project showed
Git Provider: Yes, and a production deployment was triggered from the Git commit.Why this is confusing
The current API error strongly suggests that deleting and recreating the Pages project is the only path to Git integration.
That conclusion can lead users and automation tools to perform unnecessary destructive operations, even though the Dashboard may provide a supported manual workflow.
The current Wrangler CLI surface also does not make the distinction clear:
There is no visible command or output guidance that says something like:
Expected behavior
At minimum, the Wrangler/API error message or related documentation should distinguish between:
For example, the error message could be clarified as:
Or, if the Dashboard workflow is not intended to be supported, the Dashboard and documentation should be aligned so users are not presented with conflicting behavior.
Actual behavior
sourceobject.Suggested improvement
Please clarify one of the following:
Option A: Dashboard Git binding for Direct Upload projects is supported
If this workflow is supported, please document it and mention it in Wrangler/API error output.
The error message should avoid implying that deletion/recreation is the only path.
Option B: Dashboard Git binding for Direct Upload projects is not intended to be supported
If this workflow is not intended to be supported, then the Dashboard, API, Wrangler, and docs should be aligned so users do not see contradictory behavior.
Option C: CLI/API support is planned
If Dashboard can do this safely, consider exposing the same workflow through Wrangler/API, or at least document that it is Dashboard-only.
Related issues / context
There are related issues around Pages Git integration and source management, but they do not seem to cover this exact mismatch in error guidance:
PagesProjectsource repository in-place is not possible, but no replace is performed pulumi/pulumi-cloudflare#320 discusses that updating a PagesProject source repository in place is not possible from IaC.This issue is specifically about the misleading user experience when API/Wrangler says the
sourceobject cannot be updated, while the Dashboard appears to offer a viable Git repository binding path.Impact
This affects both human users and automation tools.
When the API says the
sourceobject cannot be updated and no Dashboard path is mentioned, users may reasonably conclude that the project must be deleted and recreated. That is a destructive workaround and may cause unnecessary downtime or loss of deployment history.A clearer message would prevent avoidable destructive actions.