Documentation | 2025.1

# Projects

This section describes the configurables that can be set for projects.

If you make a configuration change, Swarm will not use it until the configuration cache has been reloaded, this forces Swarm to use the new configuration. You must be an admin or super user to reload the Swarm config cache. Navigate to the User id dropdown menu, select System Information, click the Cache Info tab, and click the Reload Configuration button.

## Restrict project name and branch definition editing to administrators

By default, once a project has been created, any member of the project can edit or delete the project's settings.

Instead of allowing any changes, or preventing all changes, you may want to prevent project members from making specific 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 Core Server can modify a project's name.
- edit_branches_admin_only: when set to true, only users with admin privileges in the Helix Core Server 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,
        ),

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 Core Server.

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'),
        ),

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

By default, projects can have a README markdown 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 displayed on the project page. See Mainline branch identification for details on configuring the project mainline.

- Valid Markdown file extensions are: md, markdown, mdown, mkdn, mkd, mdwn, mdtxt, mdtext.

If more than one README file is found, Swarm displays the first one it finds based on the order above.

- By default, Markdown support is limited to prevent execution of raw HTML and JavaScript content. The level of Markdown support can be configured by your Swarm administrator to disabled, safe, and unsafe, see Markdown.

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'    => 'enabled',
        ),

- enabled: the use of README markdown files is enabled for project overview pages, text content is displayed for project overview pages with a README markdown file. This is the default.
- disabled: the use of README markdown files is disabled for project overview pages, project overview pages are not displayed.

In Swarm 2018.3 and earlier, readme_mode could be set to disabled, restricted, or unrestricted. If your readme_mode was originally set to restricted or unrestricted and you have upgraded to Swarm 2019.1 or later, Swarm treats readme_mode as if it is set to enabled. Swarm uses the markdown configurable to determine the level of Markdown support (default is safe), see Markdown.

## Projects tab initial fetch

By default, all of the projects are fetched for the Projects tab with a single call. If your Swarm system has a large number of projects, it can take some time to populate the Projects tab. The fetch configurable is used to tell Swarm to fetch and display the first x projects and then load the rest from cache in the background. This speeds up the initial display of projects in the Projects tab.

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(
            'fetch' => array('maximum' => 50), // defaults to 0 (disabled)
        ),

The default value is 0, all projects are fetched in a single call.

## Allow project members to view project settings

When allow_view_settings is set to true, project members, owners, and administrators can view the project Settings tab. The project Automated Tests and Automated Deployment details are hidden from the project members unless they are an owner or an administrator. This enables project members to check the project settings but not change them.

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(
            'allow_view_settings' => true, // defaults to true
        ),

The default value is true.

## Prevent users from creating a branch that includes paths to which they do not have permission

By default, when creating a branch, Swarm does not check if the user has the necessary permissions for the specified path.

When permission_check is set to true, Swarm checks if the user has permissions to the specified path. If the user does not have the necessary permissions for a specified path, the creation of the branch is rejected. Only a super user, administrator, owner, or a user with write permissions is allowed to create a branch for a specific path. Swarm uses the p4 protects -M command with the ztag option to determine if a user has necessary permissions for a specified path.

If a specific branch has multiple branch paths, Swarm checks all branch paths and if the user lacks permission for a single branch, they are not allowed to delete the branch. If a user attempts to modify a project-level workflow, Swarm checks all branch paths and if the user lacks permission for a single branch, they are not allowed to edit the project-level workflow.

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

The default value is false, Swarm allows a user to create a branch with a specific path without checking if the user has access to it.

Your search for returned results