Workflow overview

Warning

Workflow is a technology preview feature and is disabled by default.

A workflow can be applied to a projectIn Helix Swarm, a group of Helix Server users who are working together on a specific codebase, defined by one or more branches of code, along with options for a job filter, automated test integration, and automated deployment. or project branch to ensure that changelists and code reviews in the project/branch follow the rules specified in that workflow. The Workflow basics section gives an overview of global workflow rules, workflow rules and how they interact with each other. There are also examples of different workflows and examples of what happens when a changelist spans multiple projects or project branches that have different workflows.

For information about the workflow rules that are available, see Workflow rules.
For information about Swarm basic workflow, see Workflow basics.
For examples of different workflows, see Example workflows.
For detailed information about how different workflows are merged, see Merging multiple workflows.

Workflow rules

A workflow is made up of the following workflow rules:

On commit without a review:

This rule is applied when a changelist without an associated review is submitted from outside of Swarm.

Select one of the following options:

Allow: the changelist is not checked, the changelist is submitted without a review.
Create a review: the changelist is submitted and a review is created automatically for the changelist.
Reject: the changelist submit is rejected.
Tip
The selected rule is also applied when a changelist is submitted with #review in the description. For more information about creating a review by including a keyword in the changelist description, see Create a review.

On commit with a review: This rule is applied when:

A Swarm review is committed.
A changelist with an associated review is submitted from outside of Swarm.

Select one of the following options:

Allow: the changelist review state is not checked. The changelist is committed even if its associated review is not approved.
Reject unless approved: the changelist is only submitted if its associated review is approved and the content of the changelist is identical to the content of the approved review.
Tip
The selected rule is also applied when a changelist is submitted with #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the description (nnnnn = review ID). For more information about adding a changelist to a review by including a keyword in the changelist description, see Add a changelist to a review.

On update of a review in an end state:

Used to stop review content being changed for reviews that are in specific states. By default, the protected end states are Archived, Rejected, and Approve:Commit. The end states are set by the Swarm administrator, see end_states.

This rule is applied when a changelist is added to a review.

Select one of the following options

Allow: the review is not checked. The changelist is added to the review no matter what the review state is. This is the default setting.
Reject: if the review is in one of the states specified in the end_state configurable:
- The Add Change button is disabled for the review.
- The changelist is rejected if it is added outside of Swarm using #review-nnnnn, #replace-nnnnn, or #append-nnnnn in the description (nnnnn = review ID).

Count votes up from:

By default, all of the up votes on a review are counted for the Minimum up votes value set on the project/branch the review is associated with. Limit the up votes that are counted to just the members of the project the review is associated with by using this rule.

This rule is applied when a user votes on a review.

Select one of the following options:

Anyone: votes are counted for all reviewers on a review. This is the default setting.
Members: only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.

Tip

For instructions on how to set Minimum up votes for projects and branches, see Project minimum up votes and Branch minimum up votes.

Automatically approve reviews:

By default, reviews must be manually approved. Enable automatic approval of reviews with this rule.

This rule is applied when a user votes on a review, a required reviewer is added to a review, or a required reviewer is made an optional reviewer on a review.

Select one of the following options:

Never: reviews are not automatically approved. This is the default setting.
Based on vote count: reviews are automatically approved if:
- There are no down votes on the review.
- There are no moderators on the review. If a review has moderators it cannot be automatically approved.
- All of the Required reviewers on the review have voted up.
- The Minimum up votes on the review has been satisfied for each of the projects and branches the review spans.
Important
Moderators prevent the automatic approval of reviews. For more information about moderators, see Moderators.
Tip
After a review has been automatically approved it needs to be manually committed.

For information about creating a new workflow, see Add a workflow.

Workflow basics

Workflows: can be associated with projects and/or project branches.
- A workflow can be created by any Swarm user.
- If a workflow is associated with any projects or project branches, that workflow cannot be deleted.
- A workflow can be shared by the workflow owner.
- A shared workflow can be viewed by any Swarm user.
- A shared workflow can be applied to a project or project branch by any Swarm user that is authorized to edit the project.
- If sharing is switched off for a workflow, any projects or branches associated with that workflow will remain associated with it.
Projects and branches:
- When a workflow is associated with a project, the workflow is used for all of the branches in that project.
- When a project branch is associated with a workflow, the workflow of the parent project is ignored and the branch workflow is used. The project workflow is replaced by the branch workflow, the workflows are not merged. For examples of why you might use this, see Restrictive project workflow with a less restrictive development branch workflow, and Project workflow with a more restrictive release branch workflow.
- When a branch is associated with a workflow and a global workflow rule is enforced (set to policy mode) by the administrator, the workflow of the parent project is ignored and the global workflow rule is merged with the branch workflow. The most restrictive rule is used.
Modifying a workflow:
- If a global workflow rule is set to default mode and that rule is modified, projects and branches that do not have an associated workflow will use the modified rule.
- If a global workflow rule is set to policy mode and the rule is modified, the entire Helix Core Server will use the modified rule.
- If a workflow is modified, any projects or branches associated with that workflow will use the modified workflow.
Global workflow rules: configured by the Swarm administrator in Global workflow, each rule can be set in one of two modes:
- Default mode: the global workflow rule is used for projects and branches that do not have an associated workflow.
  - If a project or branch has an associated workflow, the global rule is ignored for that project or branch.
  - If projects are not used, the global workflow rule applies to the entire Helix Core Server.
- Policy mode: the global workflow rule is used for the entire Helix Core Server. This allows a minimum workflow to be set for the Helix Server.
  - The global workflow rule is merged with the workflow associated with a project or branch. The most restrictive rule is used.

Example workflows

This section contains examples of typical workflows that can be configured in Swarm.

Enforce a pre-commit review workflow

To enforce a pre-commit review workflow set the rules to:

On commit without a review: set to Reject, ensures that changelist cannot be submitted without an approved review.
On commit with a review: set to Reject unless approved, ensures that if a changelist already has an associated review, that review is approved and the content of the changelist is identical to the content of the approved review.

Allow a post-commit review workflow

To allow a post-commit review workflow set the rules to:

On commit without a review: set to Create a review, ensures that all submitted changelists have a review.
On commit with a review: set to Allow, enables changelists that already have an associated review to be submitted.

Restrictive project workflow with a less restrictive development branch workflow

The release and main branches need a restrictive workflow to protect the codelines. All submissions must have an associated approved review and the content of the changelist must be identical to the content of the approved review.

The development branch can be less restrictive because you want to get features in quickly and review them after they have been committed. In this scenario you would probably want to ensure that all submitted changelists have an associated review.

Project workflow:

On commit without a review: set to Reject, ensures that changelist cannot be submitted without an approved review.
On commit with a review: set to Reject unless approved, ensures that if a changelist already has an associated review, that review is approved and the content of the changelist is identical to the content of the approved review.
On update of a review in an end state: set to Reject, ensures that the content of reviews that are considered complete cannot be changed. These end states are set by the Swarm administrator, see Protected end states.
Count votes up from: set to Members, ensures that only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.
Automatically approve reviews: set to Never, ensures that reviews are not automatically approved.

Development branch workflow:

On commit without a review: set to Create a review, ensures that all submitted changelists have a review.
On commit with a review: set to Allow, enables changelists that already have an associated review to be submitted.
On update of a review in an end state: set to Reject, ensures that the content of reviews that are considered complete cannot be changed. These end states are set by the Swarm administrator, see Protected end states.
Count votes up from: set to Anyone, ensures that votes of all reviewers on a review are counted for the Minimum up votes set on projects/branches.
Automatically approve reviews: set to Based on vote count, ensures that reviews are automatically approved when all of the review requirements have been satisfied.

Project workflow with a more restrictive release branch workflow

The project is set up with workflow that allows post commit reviews, this allows you to get features in quickly and review them after they have been committed. In this scenario it is a good idea make all submitted changelists have an associated review.

The release branch needs a more restrictive workflow to protect the codeline. All submissions must have an associated approved review and the content of the changelist must be identical to the content of the approved review.

Project workflow: defines the workflow for the project and its branches.

On commit without a review: set to Create a review, ensures that all submitted changelists have a review.
On commit with a review: set to Allow, enables changelists that already have an associated review to be submitted.
On update of a review in an end state: set to Allow, allows the content of reviews that are considered complete to be changed.
Count votes up from: set to Anyone, ensures that votes of all reviewers on a review are counted for the Minimum up votes set on projects/branches.
Automatically approve reviews: set to Based on vote count, ensures that reviews are automatically approved when all of the review requirements have been satisfied.

Release branch workflow: defines the workflow for the release branch. The workflow of the parent project is ignored and the development branch workflow is used.

On commit without a review: set to Reject, ensures that changelist cannot be submitted without an approved review.
On commit with a review: set to Reject unless approved, ensures that if a changelist already has an associated review, that review is approved and the content of the changelist is identical to the content of the approved review.
On update of a review in an end state: set to Reject, ensures that the content of reviews that are considered complete cannot be changed. These end states are set by the Swarm administrator, see Protected end states.
Count votes up from: set to Members, ensures that only the up votes of members of the project the review is associated with are counted for the Minimum up votes set on projects/branches.
Automatically approve reviews: set to Never, ensures that reviews are not automatically approved.

Merging multiple workflows

If a changelist spans multiple projects that have different workflows, the workflows are merged and the most restrictive workflow rules are used for the changelist.

Example 1: Changelist 1234 spans Project A, Project B, and Project C

Project A: //depot/jam/lib/...
Project B: //depot/jam/docs/...
Project C: //depot/common/src/...
Changelist 1234 contains the following files:
- //depot/jam/lib/tests/checkLoad.sh
- //depot/jam/docs/basics.workflow.html
- //depot/common/src/index.html

The files span all three locations so the changelist is subject to the combined workflow rules for the three locations. The most restrictive workflow is used for the changelist:

	Changelist without a review	Changelist with a review	On update of a review in an end state	Count votes up from	Automatically approve reviews
Project A workflow	Allow	Reject unless approved	Allow	Anyone	Based on vote count
Project B workflow	Allow	Reject unless approved	Reject	Members	Never
Project C workflow	Create a review	Allow	Allow	Anyone	Based on vote count
Changelist 1234 workflow	Create a review	Reject unless approved	Reject	Members	Never

Tip

The three workflows are combined and the most restrictive workflow rules are used for the changelist.

Example 2: Changelist 6789 spans Project M, Project N, and Project branch N-1

Project M: //depot/thirdparty/lib/...
Project N: //depot/thirdparty/lib/tests/...
Project branch N-1:
- //depot/projectN/...
- //depot/thirdparty/lib/...
Changelist 6789 contains the following files:
- //depot/thirdparty/lib/tests/checkReturns.sh
- //depot/projectN/src/index.html
- //depot/projectN/tests/pageLoadTest.php

The changelist files span all three locations so the changelist is subject to the combined workflow rules for the three locations. The most restrictive workflow is used for the changelist:

	Changelist without a review	Changelist with a review	On update of a review in an end state	Count votes up from	Automatically approve reviews
Project M workflow	Create a review	Reject unless approved	Allow	Anyone	Never
Project N workflow	Reject	Reject unless approved	Reject	Members	Never
Project branch N-1 workflow	Create a review	Allow	Allow	Anyone	Based on vote count
Changelist 6789 workflow	Create a review	Reject unless approved	Allow	Anyone	Never

Tip

It is important to understand that the rules for Project N are ignored because Project branch N-1 is a branch of Project N and it has its own workflow rules. This is why the result for Changelist without a review is Create review, the result for On update of a review in an end state is Allow, and the result for Count votes up from is Anyone.

Example 3: Changelist 3456 spans Project X, and Project Y

Project X: //depot/main/product/...
Project Y: //depot/main/product/docs/...
Changelist 3456 contains the following files:
- //depot/main/product/tests/fileSelector.sh
- //depot/main/product/docs/admin.html

The changelist files span both locations so the changelist is subject to the combined workflow rules for the two locations, and the global workflow rules set by the administrator. The most restrictive workflow is used for the changelist:

	Changelist without a review	Changelist with a review	On update of a review in an end state	Count votes up from	Automatically approve reviews
Project X workflow	Create a review	Allow	Allow	Anyone	Based on vote count
Project Y workflow	Reject	Allow	Reject	Anyone	Based on vote count
Global workflow rules	Create a review (policy mode)	Reject unless approved (default mode)	Allow (policy mode)	Members (policy mode)	Never (default mode)
Changelist 3456 workflow	Reject	Allow	Reject	Members	Based on vote count

Tip

Global workflow rules:
- When a global workflow rule is set to default mode, the rule is only used if the project/branch does not have an associated workflow. If the project/branch has an associated workflow, the global rule setting is ignored. This is why the result for the Changelist with a review rule is Allow, and the Automatically approve reviews is Based on vote count.
- When a global workflow rule is set to policy mode, the rule is merged with project/branch workflow and the most restrictive rule setting is used. This is why the result for the Changelist with a review rule is Reject, the result for the On Update of a review in an end state rule is Reject, and the result for Count votes up from is Members.
The global workflow rule mode determines how the global rule interacts with the workflow rules. For more information about global rule modes, see Workflow basics.
If one or more of the project branches has a moderator, the moderator prevents automatic approval of the review. For more information about moderators, see Moderators.