Add a project

  1. On the Swarm home page, click the + icon at the top-right of the projects sidebar.

    Note

    The ability to add projects can be limited to administrators only, or limited to members of specific groups. When limited, users who are not administrators, or a member of the specified group, will not see the + icon at the top-right of the projects sidebar.

    The Add Project page appears:

  2. Provide a name for the project.
  3. Optionally provide a description.
  4. Optionally select the Only Owners and Administrators can edit the project checkbox. When checked, a field is displayed allowing you to add a new owner. The field auto-suggests users within Helix server as you type.

    Note

    You cannot specify a group as an owner.

    Once specified, modifying the project's definition is restricted to project owners and administrators (users with admin-level or super-level privileges in Helix server).

  5. Specify at least one team member. This field auto-suggests projects, groups, and users within Helix server as you type (up to a combined limit of 20 entries).

    Important

    During project creation, if you do not have admin privileges and you do not add yourself as a member or as an owner, you cannot edit this project's configuration later.

    See Membership for more details.

  6. Optionally click the Private checkbox to make this project private. Private projects and their associated reviews are only visible to project owners, moderators, and members, plus users with super privileges in Helix server.

    For more information, see Private projects.

  7. Optionally click the Add Branch link to display the branch drop-down dialog.

    1. Enter a short Name for the branch.
    2. Enter one or more branch paths, one per line.

      Note

      Each branch path should be expressed in depot syntax. Wildcards should not be used; the only exception is that the branch path can end with the Helix Core wildcard ...

      For more information, see "File Specifications" in P4 Command Reference.

    3. Optionally check the Only Moderators can approve or reject reviews checkbox. When checked, a field is displayed allowing you to add a new moderator. The field auto-suggests groups and users within Helix server Engine as you type.

      If a group is specified as a moderator, all of the members of that group have the same moderator privileges for that project branch as if they were added individually.

      Once the branch specification is complete and the project has been saved, changing the state of any review associated with this moderated branch is restricted as follows:

      • Only moderators can approve or reject the review. Moderators can also transition a review to any other state.
      • The review's author, when not a moderator, can change the review's state to Needs Review, Needs Revision, Archived, and can attach committed changelists.

        Normally, the review's author cannot change the review's state to Approved or Rejected on moderated branches. However, authors that are also moderators have moderator privileges, and may approve or reject their own review.

        When disable_self_approve is enabled, authors who are moderators (or even users with admin privileges) cannot approve their own reviews.

      • Project members can change the review's state to Needs Review or Needs Revision, and can attach committed changelists. Project members cannot change the review's state to Approved, Rejected, or Archived.
      • Users that are not project members, moderators, or the review's author cannot transition the review's state.
      • For the review's author and project members, if a review is not in one of their permitted states, for example if the review's state is Rejected, they cannot transition the review to another state.

        These restrictions have no effect on who can start a review.

    4. Click the Done button to accept your branch specification.

    Once the branch definition has completed, if any moderators were specified, the number of moderators for that branch is displayed in the list of branches:

  8. Optionally specify a job filter. The job filter allows you to specify criteria that are used to associate jobs with projects. For example, entering Subsystem=ProjectA associates jobs whose subsystem field is set to ProjectA with the current project.

    Note

    This job filter is simpler than the filters available in other Helix Core clients. The filter must be expressed as field=value pairs; bare keywords are not permitted. The asterisk for wildcard matching is permitted, but no other filter expression syntax is permitted.

  9. By default project members and moderators are notified when a new review is started. Project members, moderators, and followers are notified when a change is committed.

    Select which actions send a notification:

    Note
    • When a group is a project member or project moderator, all of the members of that group are notified using the same logic as for individual project members and moderators.
    • Any @mention users and groups, or users and groups who are explicitly added to a review or changelist, will receive notifications even if new review/committed review notifications are disabled.
  10. Optionally click the Enable checkbox beside Automated Tests to display the automated tests configuration fields.

    Specify a URL that triggers a test execution. Use the special arguments described in the dialog to help compose a URL that informs your test suite with important details. For more details, see How can I integrate my test suite to inform review acceptance or rejection?

  11. Optionally click the Enable checkbox beside Automated Deployment to display the automated deployment configuration fields.

    Specify a URL that triggers a deployment of the project's code. Use the special arguments described in the dialog to help compose a URL that informs your deployment program with important details. For more details, see How can I automatically deploy code within a review?

  12. Click Save.

    Note

    The Save button is disabled if any required fields are empty.

    Important

    It is possible to create a project that you cannot edit. This can happen if you have specified owners but not yourself as an owner, or if you have not specified yourself as a member. Swarm can detect some (but not all) such situations when you save a project; when it does detect such a situation, a warning dialog is displayed.

    If you see this dialog, click Continue to save the project without your ownership/membership, or click Cancel within the dialog to continue editing the project. The project page's Save and Cancel buttons are disabled while this dialog is visible.