Resource protection and project approval policies
Project policies, as described in this documentation, currently only apply to Workshop modules. Project policies will eventually be available for more resources, including Ontology and Pipeline Builder resources.
Protecting resources through branching and approval policies ensures that all contributions are made safely and in a controlled manner. When resources are protected, changes must be submitted via branches and can only be merged after receiving approval according to the project's defined policies.
Resource protection
To safeguard critical workflows or maintain development best practices, you can choose to protect the main branch of your resources. Protected resources cannot be changed directly; instead, changes must be made on a branch and then approved before taking effect on the main branch.
A branch may include both protected and unprotected resources; however, only protected resources require changes to be made on a branch in accordance with the project’s approval policy. Changes to unprotected resources will still require approval from a user with edit-level permissions unless specified otherwise.
Protected resources can be identified by the 
icon (branch lock) in the Compass file system.
Any user with owner permissions on a resource can choose to protect or unprotect that resource. Resources can be protected from your file system, individually or in bulk (by multi-selection). To protect a resource, right-click on a resource and choose Protect or Unprotect (depending on the current status). Workshop resources can also be protected from within the Workshop application by navigating to Settings and choosing the Branch protection tab.
Branch protection tab
The branch protection tab in a project serves two purposes:
- Defining branch approval policy: Owners of projects can define a project approval policy in the branch protection tab.
- Automatically protecting new files: When toggled on, this setting will automatically protect all new files created in the project.
If Automatically protect new resources is enabled for a project, Marketplace installs may fail to update Workshop modules. This is because any newly created Workshop modules will be automatically protected, and Marketplace does not support making changes on branches. To resolve Workshop module update issues, unprotect any module that may have had a failed update and re-run the Marketplace install.
Project approval policies
Once a resource is protected, any change to that resource will have to be made on a branch and go through an approval process. The approval policy is set at the project level, and defines the approval required to merge changes to protected resources.
Default approval policy
Projects come with a default approval policy, which requires at least one user with edit permissions to approve changes, and allows contributors to a resource to approve their own changes. Approval will also happen automatically if the user has edit permissions. A rejection from any reviewer will block the proposal from being merged.
Example project with default approval policy:
Custom approval policy
Approval policies have three customizable parameters:
- Eligible reviewers: Users or groups allowed to review and approve changes to the main branch of a protected resource.
- Number of approvals required: The minimum number of approvals needed.
- Contributor approval: Specify whether contributors to the resource are allowed to approve changes to that resource. A contributor is any user who has made a change to that resource on the branch.
Once a policy has been created on a project, it will apply immediately to all protected resources in that project when you create a branch and then a proposal. Additionally, if you update the policy to be more or less restrictive, proposals linked to that policy will be refreshed and have their status reevaluated against the new policy requirements. Only users that are owners on the project can update its custom policy.
Example project with custom approval policy:
Moving a resource to a new project
A resource's protection status is preserved when moving resources between projects. For example:
- Moving a protected resource to a new project: The resource will remain protected in the new project.
- Moving an unprotected resource to a new project: The resource will remain unprotected in the new project.
When a protected resource moves to a new project, any change to that protected resource must be made on a branch and will be governed by the approval policy of the new project.
If a resource with an open proposal is moved to a new project, the existing proposal may take up to 1 day before the resource's policy displays the new project policy. Updating the module on the branch or attempting to merge the proposal will also trigger a refresh of the resource's policy to match the new project policy.
Project policies and local branch protection mechanisms
Code repositories and Pipeline Builder both have local branch protection mechanisms and approval policies. These will remain in place.
In the future, users will have the option to opt into the project approval policy for their code repositories and builder pipelines.
Branch protection in Workshop modules
When on the main branch, the Save and publish button on protected Workshop modules is replaced with a Save to new branch button, requiring all changes to be made on a branch rather than directly to main.
Selecting Save to new branch will prompt you to create a new branch. You can give the branch a name and select the ontology for the branch.
Once you are ready to merge your changes to main, create a proposal.
Approval process for Workshop modules
Once a proposal is created, reviewers will be notified to review the changes. Navigating to the branched version of the Workshop module will direct reviewers to the Changelog tab in Workshop.
Within the Changelog tab, reviewers can see the changes made to the module. Reviwers can then approve or reject the change by selecting the appropriate Approve or Reject button on the left panel in the Review proposed changes section.
