Project policies, as described in this documentation, currently only apply to Workshop modules and ontology resources migrated to project permissions. Project policies will eventually be available for more resources, including Pipeline Builder and AIP Logic.
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.
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.
The branch protection tab in a project serves two purposes:
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.
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:
Approval policies have three customizable parameters:
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:
A resource's protection status is preserved when moving resources between projects. For example:
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.
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.
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.
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.
The ontology resource types supported by branch protection include:
Notably, resource protection settings are not supported on:
Additionally, ontology resources must be migrated to use project permissions before they can be protected. For more information, review ontology permissions.
After migrating an ontology resource to use project permissions, you can view and manage its protection status via the parent project's Files tab.
Once protection is enabled, you must make changes on a separate branch and create a proposal to merge them into the main branch.
The protection status is also visible in Ontology Manager on the Overview tab:
Additionally, you can review the applicable policy under the Security tab:
When modifying protected resources, the Save dialog is replaced with Create and save to branch, requiring you to save changes to a new branch.
Once a proposal is created, reviewers added via the Foundry Branching application will be notified to review the changes.
In the ontology proposal, reviewers can view the proposal details and approve or reject changes to all modified resources or to specific ontology resources.
Once the policy requirements are met, approved resources change from In Progress
to Approved
. You can then merge the proposal if all other checks have passed.