Projects

By default, once a project has been created, any member of the project can edit or delete the project's settings. Projects can also set Only Owners and Administrators can edit the project, which prevents all project changes by users who are neither owners or administrators.

Instead of allowing any changes, or preventing all changes, you may want to prevent project members from making select changes, such as to the project's name (and associated identifier), or adjusting the branch definition(s). This is useful when build infrastructure or other tooling treats these details as operational configuration, but you still want members to be able to adjust other aspects of the project configuration.

To do so, edit the SWARM_ROOT/data/config.php file, and set the following two items, similar to the following example: 

  'projects' => array(
      'edit_name_admin_only'     => true,
      'edit_branches_admin_only' => true,
  ),

  • edit_name_admin_only: when set to true, only users with admin privileges in the Helix Versioning Engine can modify a project's name.

  • edit_branches_admin_only: when set to true, only users with admin privileges in the Helix Versioning Engine can modify a project's branch definition(s).

Both items default to false.

Limit adding projects to administrators

By default, any authenticated user can add new projects. Swarm can restrict project creation to users with admin-level privileges or higher. Once restricted, Swarm prevents non-administrators from adding projects, and does not display the + icon to add a project to non-administrators.

Add or update the following configuration block to the SWARM_ROOT/data/config.php file, at the same level as the p4 entry: 

<?php
    // this block should be a peer of 'p4'
    'projects' => array(
        'add_admin_only' => true,
    ),

Important

If add_admin_only is enabled and add_groups_only has one or more groups configured, project creation is only available to users with administrator privileges and who are members of the specified groups.

Limit adding projects to members of specific groups

Swarm can restrict project creation to members of specific groups. The groups and membership need to be defined in the Helix Versioning Engine.

Add or update the following configuration block to the SWARM_ROOT/data/config.php file, at the same level as the p4 entry: 

<?php
    // this block should be a peer of 'p4'
    'projects' => array(
        'add_groups_only' => array('wizards', 'slayers', 'phbs'),
    ),

Important

If add_admin_only is also enabled, project creation is only available to users with administrator privileges and who are members of the specified groups.

Project readme

Projects can have a README.md file associated with them that is automatically displayed on the project overview page. This file is read from the root of the project's mainline if it is available, and shown above the activity feed. See Mainline branch identification for details on configuring the project mainline.

Add or update the following configuration block to the SWARM_ROOT/data/config.php file, at the same level as the p4 entry: 

<?php
    // this block should be a peer of 'p4'
    'projects' => array(
      'readme_mode'    => 'restricted',
    ),

  • disabled: the use of README.md file will be disabled and no text content will be shown in the project overview. page.

  • restricted: the content of the README.md file is displayed, but Markdown support is limited to prevent inclusion of raw HTML and Javascript content. This is the default.

  • unrestricted: the content of the README.md file is displayed, and Markdown support is unrestricted, allowing full HTML and Javascript to be used. This is insecure as any person with access to the README.md file can add script to the page which would execute as the currently logged in user.

Changing the project sidebar order

The sort order of the project sidebar on the home page is alphabetical. In order to change it to an order based on project popularity, add the following configuration block to the SWARM_ROOT/data/config.php file, at the same level as the p4 entry: 

<?php
    // this block should be a peer of 'p4'
    'projects' => array(
      'sidebar_sort_field'       => 'rank'
    ),

The options for the sidebar_sort_field are name, rank and id:

  • name: sort alphabetically according to the project display name. This is the default sort order.

  • id: sort alphabetically according to the internal project id.

  • rank: sort according to the popularity of the project. This is based on the number of followers and members that the project has.