{"record":{"id":"163adb638a715c03","repo":"theonedev/onedev","slug":"generated-branch-name-is-only-available-when-issue","errorCode":null,"errorMessage":"Generated branch name is only available when issue state triggers are used","messagePattern":"Generated branch name is only available when issue state triggers are used","errorType":"validation","errorClass":"ExplicitException","httpStatus":null,"severity":"error","filePath":"server-core/src/main/java/io/onedev/server/buildspec/step/branchnameprovider/GeneratedBranchName.java","lineNumber":21,"sourceCode":"import io.onedev.commons.utils.ExplicitException;\nimport io.onedev.server.OneDev;\nimport io.onedev.server.annotation.Editable;\nimport io.onedev.server.model.Build;\nimport io.onedev.server.service.IssueService;\n\n@Editable(order=100, name=\"Use generated branch name\", description=\"\"\"\n        Generate branch name based on issue title. It is highly recommended to configure \n\t\tAI model in <i>Administration / AI Settings</i> to generate good branch name\"\"\")\npublic class GeneratedBranchName implements BranchNameProvider {\n\n\tprivate static final long serialVersionUID = 1L;\n\n\t@Override\n\tpublic String getBranchName(Build build) {\n\t\tif (build.getIssue() != null) {\n\t\t\treturn OneDev.getInstance(IssueService.class).suggestBranch(build.getIssue());\n\t\t} else {\n\t\t\tthrow new ExplicitException(\"Generated branch name is only available when issue state triggers are used\");\n\t\t}\n\t}\n\n}\n","sourceCodeStart":3,"sourceCodeEnd":26,"githubUrl":"https://github.com/theonedev/onedev/blob/d44925c47c37992c828ea673a5f9620539bc3ff2/server-core/src/main/java/io/onedev/server/buildspec/step/branchnameprovider/GeneratedBranchName.java#L3-L26","documentation":"GeneratedBranchName is a branch name provider that asks IssueService.suggestBranch to derive a branch name from the build's linked issue. Branch suggestions only exist for builds triggered by issue state transitions, so when build.getIssue() is null this ExplicitException is thrown.","triggerScenarios":"Using branchName: !<GeneratedBranchName> on a build that has no associated issue — i.e. triggered by commit push, cron, or manual dispatch instead of an issue state trigger (IssueStateActivation).","commonSituations":"Reusing a CI job definition that works for issue-fix builds on regular push builds; configuring the branch name provider on a job scheduled by cron; issue linkage lost because the commit was not made with the suggested branch name pattern.","solutions":["Only use GeneratedBranchName for jobs triggered by issue state activation (build.getIssue() != null).","For push/cron builds, use a fixed branch name or a different branch name provider.","Ensure contributors create commits on branches matching the issue's suggested branch pattern so the issue is linked to the build.","Add a condition to the job so it only runs for issue-triggered builds."],"exampleFix":"// before (runs on push too)\nbranchName: !<GeneratedBranchName>\n// after: guard the job with an issue state trigger, or use a literal\nbranchName: feature/manual-build","handlingStrategy":"try-catch","validationCode":"// Only configure GeneratedBranchName under an issue state trigger\nif (build.getIssue() == null) {\n    branchName = \"manual-\" + build.getCommitId().substring(0, 8); // fallback for non-issue builds\n} else {\n    branchName = OneDev.getInstance(IssueService.class).suggestBranch(build.getIssue());\n}","typeGuard":null,"tryCatchPattern":"// catch ExplicitException and fall back\ntry {\n    branchName = generatedBranchName.getBranchName(build);\n} catch (ExplicitException e) {\n    branchName = \"fallback-branch\";\n}","preventionTips":["Use GeneratedBranchName only with issue state activation triggers.","Add job conditions restricting the job to issue-triggered builds.","Educate contributors to use the suggested branch name so builds link to issues."],"tags":["ci","issues","branch","build-trigger"],"backgroundTag":"invalid-state-transition","analyzedSha":"d44925c47c37992c828ea673a5f9620539bc3ff2","analyzedAt":"2026-09-06T07:18:27.995Z","contentChangedAt":"2026-09-06T07:18:27.995Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}