Octopus "Failed to update a version-controlled project" (config as code) in CI
For a config-as-code (version-controlled) project, Octopus reads and writes the deployment process from a Git repository. This fails when the Git credential is wrong, the referenced branch does not exist, or a commit conflicts, so create-release cannot resolve the process.
What this error means
octo create-release against a version-controlled project fails with "Failed to update the version-controlled project", "branch not found", or a Git authentication error.
octo create-release --project "Web" --gitRef "refs/heads/main"
Failed to update the version-controlled project 'Web': the branch 'main'
could not be found in the associated Git repository.Common causes
The referenced branch or gitRef is wrong
The --gitRef or default branch does not exist in the project repository, so Octopus cannot read the deployment process from it.
Git credentials or a commit conflict
The stored Git credential is invalid or lacks access, or a concurrent change created a conflict, so the version-controlled write or read fails.
How to fix it
Reference a real branch and valid credentials
- Confirm the branch exists in the project Git repository.
- Pass a valid --gitRef, or use the default branch that exists.
- Verify the Octopus Git credential has access to the repository.
octo create-release --project "Web" --gitRef "refs/heads/main" \
--server "$OCTOPUS_URL" --apiKey "$OCTOPUS_API_KEY"Resolve a Git conflict before releasing
If the failure is a commit conflict, reconcile the project repository so the deployment process is consistent, then re-run create-release.
How to prevent it
- Reference branches that exist in the project Git repository.
- Keep the Octopus Git credential valid and scoped to the repo.
- Avoid concurrent edits to the version-controlled process during releases.