Workflow overview

Note
  • For Swarm 2019.2 and later, the workflow feature is enabled by default. If the workflow feature is not working, ask your Swarm administrator to check that the workflow prerequisites have been met, see Workflow prerequisites.

  • The Swarm administrator can give individual groups and users special permission to ignore all of the Swarm workflow rules. Typically, these permissions are given to a small set of trusted groups and users, for example project owners and administrators. For more information about excluding users and groups from being bound by the workflow rules, see Members or groups who can ignore ALL workflow rules.

Tip

To understand the benefits of using the Swarm Workflow feature, see Why should I use Swarm workflow?

A workflow can be applied to a projectClosed In Helix Swarm, a group of Helix Core 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 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.

Sections in this chapter:

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 automatically 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.

Tip

When a review is in a protected end state, it can still be updated manually by a user from the Swarm UI.

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.

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.
    • All of the tests configured to block approval have passed.
    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 set to Enforce on 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 Enforce off 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 Enforce on 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 rules, each rule can be set in one of two modes:
    • Enforce off: 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.
    • Enforce on: the global workflow rule is used for the entire Helix Core Server. This allows a minimum workflow to be set for the Helix Core Server.
      • The global workflow rule is merged with the workflow associated with a project or branch. The most restrictive rule is used.
  • Tests:
    • If a test is associated with a workflow, it can be configured to run when a review associated with that workflow is either created/updated or submitted, or run manually from the review.
    • If a test is associated with the global workflow, it can be configured to run when a review is either created/updated or submitted, or run on manually from the review.
    • If a test is associated with a workflow or a global workflow, it can be configured to block approval if it fails.

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. All of the tests associated with the merged workflows are run. If there are any duplicate tests they are only run once.

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 Workflow Tests
Project A workflow Allow Reject unless approved Allow Anyone Based on vote count Smoke Test A
Project B workflow Allow Reject unless approved Reject Members Never Smoke Test B
Project C workflow Create a review Allow Allow Anyone Based on vote count

Smoke Test B

Smoke Test C

Changelist 1234 workflow Create a review Reject unless approved Reject Members Never

Smoke Test A

Smoke Test B

Smoke Test C

Tip

The three workflows are combined and the most restrictive workflow rules are used for the changelist. All of the tests associated with the three workflows are run but Smoke Test B on Project A and Project B is only run once.

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 Workflow Tests
Project M workflow Create a review Reject unless approved Allow Anyone Never Smoke Test M
Project N workflow Reject Reject unless approved Reject Members Never Smoke Test N
Project branch N-1 workflow Create a review Allow Allow Anyone Based on vote count Smoke Test N-1
Changelist 6789 workflow Create a review Reject unless approved Allow Anyone Never

Smoke Test M

Smoke Test N-1

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 Workflow Tests
Project X workflow Create a review Allow Allow Anyone Based on vote count Smoke Test X
Project Y workflow Reject Allow Reject Anyone Based on vote count Smoke Test Y
Global workflow rules Create a review (Enforce on) Reject unless approved (Enforce off) Allow (Enforce on) Members (Enforce on) Never (Enforce off)

Global Smoke Test

Global Full Test

Changelist 3456 workflow Reject Allow Reject Members Based on vote count

Smoke Test X

Smoke Test Y

Global Smoke Test

Global Full Test

Tip
  • Global workflow rules:
    • When a global workflow rule is set to Enforce off, 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 Enforce on, the rule is merged with project/branch workflow and the most restrictive rule setting is used. This is why the result for the Changelist without 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.