Skip to content

Create a branch in a Git repository

Creates a branch directly in the central repository Clarive hosts, then registers that branch as a revision resource so the rest of the product can select it. No clone and no push are involved, so the branch is visible to every client as soon as the op returns.

Use it for the branch a workflow owns: a feature branch cut when a topic enters development, or a release branch cut from an environment tag. For a fixed marker that nothing will advance, use Create a tag in a Git repository instead.

resolve the base ref create or move the branch revision resource already registered for this name? not found op stops, later repositories untouched yes reused as is, the commit it records is not refreshed no a new revision resource is recorded

Fields

Repository

The repositories that get the branch. The picker takes more than one entry, and each entry gets the same branch name cut from the same base ref. The list offers variables as well as repository resources, so ${repository} is a legal entry, and a variable resolving to several ids separated by commas expands into several repositories.

Blank stops the op with a missing-repository error before anything is written.

Sha or Ref

Where the new branch starts. Any ref Git resolves is accepted: a branch name, a tag, a short or full commit id, or an expression such as master~1. The field expands ${var} placeholders against the stash.

This value is checked before the branch is written, and a value Git cannot resolve stops the op with an error naming both the base you gave and the branch you asked for. That check is per repository, so a tag that exists in one repository and not in another fails on the second one after the first has already been branched.

Blank stops the op with a missing-sha error.

Branch Name

The name of the branch to create. Expands ${var}. Slashes are fine, which is how names like feature/${topic_id} are built. The value is used exactly as typed, with no prefix and no cleanup, so spaces or a leading dash make Git reject it and the op fails.

Blank stops the op with a missing-branch-name error.

Move to new sha if branch exists?

Off by default.

Off, a branch name that already exists in the repository fails the op, which makes the op a safe "create once" step you can leave in a rule that runs repeatedly.

On, the existing branch is repointed at the base ref. This is a pointer move, not a merge: nothing is rebased, nothing is merged, and any commit reachable only from the old position stops being reachable from that branch. Anyone with the old branch checked out has to reset.

What ends up in Clarive

Beyond the branch itself, the op records the branch as a revision resource named after the branch, attached to the repository, so it turns up in revision pickers and in anything that lists branches as resources.

The op returns the list of resource ids it produced, one per repository, in picker order. Set a Return Key on the op to capture that list in the stash and hand it to a later op.

The registration step runs once. If a revision resource with the same name already exists for that repository, it is reused and the commit it records is left alone. With Move to new sha if branch exists? on, that means the branch in Git moves while the recorded commit still refers to wherever the branch stood when the resource was first created. Read the branch from Git, not from that record, when the distinction matters.

Failure, ordering and rollback

Repositories are processed in picker order and the first failure stops the op. Repositories already handled keep their new branch and their new revision resource; the rest are untouched and nothing is rolled back.

Every new op runs in both directions by default, so an unchanged branch op runs again during a rollback pass. With the force option off that second run fails, because the branch it is trying to create already exists. Untick Run Rollback, or pair it with Delete a reference in a Git repository on the rollback path.

Combining with other ops

Cut the branch, then feed the same name into Merge a branch in a Git repository as the topic branch once work on it has finished, and into Delete a reference in a Git repository to retire it afterwards.

To branch a set of repositories that is only known at run time, put this op inside FOREACH CI and pass the loop variable into Repository.

Guard the op with IF var condition THEN when the branch should only be cut for certain topic statuses or environments, and use LOG right after it to record the name in the job log, since the op itself logs nothing at normal verbosity.

Examples

Cut a feature branch for a topic from the integration branch, once, failing loudly if a branch by that name is already there.

Repository   ${repository}
Sha or Ref   develop
Branch Name  feature/${topic_id}
Move to new sha if branch exists?   off

Keep a per-environment branch pointing at whatever was last promoted, across every repository in a list variable. Force is required here, since the branch exists after the first run.

Repository   ${project_repos}
Sha or Ref   ${job_branch}
Branch Name  env/${bl}
Move to new sha if branch exists?   on

Cut a release branch from an existing tag and keep the resource ids for the next op by setting the op's Return Key to release_revisions.

Repository   ${repository}
Sha or Ref   release/${previous_version}
Branch Name  release/${version}
Move to new sha if branch exists?   off