Resource protection and project approval policies

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 policies in the branch protection tab.
• Automatically protecting new files: When toggled on, this setting will automatically protect all new files created in the project.

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.

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.

Branch protection for ontology resources

The ontology resource types supported by branch protection include:

• Object types
• Action types
• Link types
• Interface types
• Shared property types

Notably, resource protection settings are not supported on:

• Type groups
• Rule sets (When modifying a rule set, the protection status of the containing object type will be enforced.)

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.

Approval process for ontology resources

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.

Known limitations

• Indexing an object type counts as a modification. If the resource is protected by a project policy, you will need policy approval to merge your branch. To bypass this requirement, remove indexing changes before merging.
• Currently, adding reviewers to one resource adds them to the entire proposal, as ontology changes are grouped together. Only users in a resource's project policy are required to approve that specific resource.