Skip to content
Ona Docs

Policies

GetOrganizationPolicies
organizations.policies.retrieve(PolicyRetrieveParams**kwargs) -> PolicyRetrieveResponse
POST/gitpod.v1.OrganizationService/GetOrganizationPolicies
UpdateOrganizationPolicies
organizations.policies.update(PolicyUpdateParams**kwargs) -> object
POST/gitpod.v1.OrganizationService/UpdateOrganizationPolicies
ModelsExpand Collapse
class AgentPolicy:

AgentPolicy contains agent-specific policy settings for an organization

command_deny_list: List[str]

command_deny_list contains a list of commands that agents are not allowed to execute

mcp_disabled: bool

mcp_disabled controls whether MCP (Model Context Protocol) is disabled for agents

scm_tools_disabled: bool

scm_tools_disabled controls whether SCM (Source Control Management) tools are disabled for agents

conversation_sharing_policy: Optional[ConversationSharingPolicy]

conversation_sharing_policy controls whether agent conversations can be shared

One of the following:
"CONVERSATION_SHARING_POLICY_UNSPECIFIED"
"CONVERSATION_SHARING_POLICY_DISABLED"
"CONVERSATION_SHARING_POLICY_ORGANIZATION"
max_subagents_per_environment: Optional[int]

max_subagents_per_environment limits the number of non-terminal sub-agents a parent can have running simultaneously in the same environment. Valid range: 0-10. Zero means use the default (5).

formatint32
maximum10
scm_tools_allowed_group_id: Optional[str]

scm_tools_allowed_group_id restricts SCM tools access to members of this group. Empty means no restriction (all users can use SCM tools if not disabled).

Literal["CONVERSATION_SHARING_POLICY_UNSPECIFIED", "CONVERSATION_SHARING_POLICY_DISABLED", "CONVERSATION_SHARING_POLICY_ORGANIZATION"]

ConversationSharingPolicy controls how agent conversations can be shared.

One of the following:
"CONVERSATION_SHARING_POLICY_UNSPECIFIED"
"CONVERSATION_SHARING_POLICY_DISABLED"
"CONVERSATION_SHARING_POLICY_ORGANIZATION"
class CrowdStrikeConfig:

CrowdStrikeConfig configures CrowdStrike Falcon sensor deployment

additional_options: Optional[Dict[str, str]]

additional_options contains additional FALCONCTL_OPT_* options as key-value pairs. Keys should NOT include the FALCONCTL_OPT_ prefix.

cid_secret_id: Optional[str]

cid_secret_id references an organization secret containing the Customer ID (CID).

formatuuid
enabled: Optional[bool]

enabled controls whether CrowdStrike Falcon is deployed to environments

image: Optional[str]

image is the CrowdStrike Falcon sensor container image reference

tags: Optional[str]

tags are optional tags to apply to the Falcon sensor (comma-separated)

class CustomAgentEnvMapping:

CustomAgentEnvMapping maps a script placeholder to an organization secret. The backend resolves the secret name to a UUID at runtime.

name: Optional[str]

name is the environment variable name used as a placeholder in the start command.

secret_name: Optional[str]

secret_name is the name of the organization secret whose value populates this placeholder.

class CustomSecurityAgent:

CustomSecurityAgent defines a custom security agent configured by an organization admin.

id: Optional[str]

id is a unique identifier for this custom agent within the organization. Server-generated at save time if empty.

description: Optional[str]

description is a human-readable description of what this agent does

enabled: Optional[bool]

enabled controls whether this custom agent is deployed to environments

env_mappings: Optional[List[CustomAgentEnvMapping]]

env_mappings maps script placeholders to organization secret names, resolved to secret values at runtime.

name: Optional[str]

name is the environment variable name used as a placeholder in the start command.

secret_name: Optional[str]

secret_name is the name of the organization secret whose value populates this placeholder.

name: Optional[str]

name is the display name for this custom agent

start_command: Optional[str]

start_command is the shell script that starts the agent

Literal["KERNEL_CONTROLS_ACTION_UNSPECIFIED", "KERNEL_CONTROLS_ACTION_BLOCK", "KERNEL_CONTROLS_ACTION_AUDIT"]

KernelControlsAction defines how a kernel-level policy violation is handled.

One of the following:
"KERNEL_CONTROLS_ACTION_UNSPECIFIED"
"KERNEL_CONTROLS_ACTION_BLOCK"
"KERNEL_CONTROLS_ACTION_AUDIT"
class OrganizationPolicies:
agent_policy: AgentPolicy

agent_policy contains agent-specific policy settings

command_deny_list: List[str]

command_deny_list contains a list of commands that agents are not allowed to execute

mcp_disabled: bool

mcp_disabled controls whether MCP (Model Context Protocol) is disabled for agents

scm_tools_disabled: bool

scm_tools_disabled controls whether SCM (Source Control Management) tools are disabled for agents

conversation_sharing_policy: Optional[ConversationSharingPolicy]

conversation_sharing_policy controls whether agent conversations can be shared

One of the following:
"CONVERSATION_SHARING_POLICY_UNSPECIFIED"
"CONVERSATION_SHARING_POLICY_DISABLED"
"CONVERSATION_SHARING_POLICY_ORGANIZATION"
max_subagents_per_environment: Optional[int]

max_subagents_per_environment limits the number of non-terminal sub-agents a parent can have running simultaneously in the same environment. Valid range: 0-10. Zero means use the default (5).

formatint32
maximum10
scm_tools_allowed_group_id: Optional[str]

scm_tools_allowed_group_id restricts SCM tools access to members of this group. Empty means no restriction (all users can use SCM tools if not disabled).

allowed_editor_ids: List[str]

allowed_editor_ids is the list of editor IDs that are allowed to be used in the organization

allow_local_runners: bool

allow_local_runners controls whether local runners are allowed to be used in the organization

default_editor_id: str

default_editor_id is the default editor ID to be used when a user doesn’t specify one

default_environment_image: str

default_environment_image is the default container image when none is defined in repo

maximum_environments_per_user: str

maximum_environments_per_user limits total environments (running or stopped) per user

maximum_running_environments_per_user: str

maximum_running_environments_per_user limits simultaneously running environments per user

members_create_projects: bool

members_create_projects controls whether members can create projects

members_require_projects: bool

members_require_projects controls whether environments can only be created from projects by non-admin users

organization_id: str

organization_id is the ID of the organization

formatuuid
port_sharing_disabled: bool

port_sharing_disabled controls whether user-initiated port sharing is disabled in the organization. System ports (VS Code Browser, agents) are always exempt from this policy.

require_custom_domain_access: bool

require_custom_domain_access controls whether users must access via custom domain when one is configured. When true, access via app.gitpod.io is blocked.

restrict_account_creation_to_scim: bool

restrict_account_creation_to_scim controls whether account creation is restricted to SCIM-provisioned users only. When true and SCIM is configured for the organization, only users provisioned via SCIM can create accounts.

delete_archived_environments_after: Optional[str]

delete_archived_environments_after controls how long archived environments are kept before automatic deletion. 0 means no automatic deletion. Maximum duration is 4 weeks (2419200 seconds).

formatregex
editor_version_restrictions: Optional[Dict[str, EditorVersionRestrictions]]

editor_version_restrictions restricts which editor versions can be used. Maps editor ID to version policy, editor_version_restrictions not set means no restrictions. If empty or not set for an editor, we will use the latest version of the editor

allowed_versions: Optional[List[str]]

allowed_versions lists the versions that are allowed If empty, we will use the latest version of the editor

Examples for JetBrains: ["2025.2", "2025.1", "2024.3"]

maximum_environment_lifetime: Optional[str]

maximum_environment_lifetime controls for how long environments are allowed to be reused. 0 means no maximum lifetime. Maximum duration is 180 days (15552000 seconds).

formatregex
maximum_environment_timeout: Optional[str]

maximum_environment_timeout controls the maximum timeout allowed for environments in seconds. 0 means no limit (never). Minimum duration is 30 minutes (1800 seconds). value must be 0s (no limit) or at least 1800s (30 minutes):

this == duration('0s') || this >= duration('1800s')
formatregex
security_agent_policy: Optional[SecurityAgentPolicy]

security_agent_policy contains security agent configuration for the organization. When configured, security agents are automatically deployed to all environments.

crowdstrike: Optional[CrowdStrikeConfig]

crowdstrike contains CrowdStrike Falcon configuration

additional_options: Optional[Dict[str, str]]

additional_options contains additional FALCONCTL_OPT_* options as key-value pairs. Keys should NOT include the FALCONCTL_OPT_ prefix.

cid_secret_id: Optional[str]

cid_secret_id references an organization secret containing the Customer ID (CID).

formatuuid
enabled: Optional[bool]

enabled controls whether CrowdStrike Falcon is deployed to environments

image: Optional[str]

image is the CrowdStrike Falcon sensor container image reference

tags: Optional[str]

tags are optional tags to apply to the Falcon sensor (comma-separated)

veto_exec_policy: Optional[VetoExecPolicy]

veto_exec_policy contains the veto exec policy for environments.

action: Optional[KernelControlsAction]

action specifies what action kernel-level controls take on policy violations

One of the following:
"KERNEL_CONTROLS_ACTION_UNSPECIFIED"
"KERNEL_CONTROLS_ACTION_BLOCK"
"KERNEL_CONTROLS_ACTION_AUDIT"
enabled: Optional[bool]

enabled controls whether executable blocking is active

executables: Optional[List[str]]

executables is the list of executable paths or names to block

class SecurityAgentPolicy:

SecurityAgentPolicy contains security agent configuration for an organization. When enabled, security agents are automatically deployed to all environments.

crowdstrike: Optional[CrowdStrikeConfig]

crowdstrike contains CrowdStrike Falcon configuration

additional_options: Optional[Dict[str, str]]

additional_options contains additional FALCONCTL_OPT_* options as key-value pairs. Keys should NOT include the FALCONCTL_OPT_ prefix.

cid_secret_id: Optional[str]

cid_secret_id references an organization secret containing the Customer ID (CID).

formatuuid
enabled: Optional[bool]

enabled controls whether CrowdStrike Falcon is deployed to environments

image: Optional[str]

image is the CrowdStrike Falcon sensor container image reference

tags: Optional[str]

tags are optional tags to apply to the Falcon sensor (comma-separated)

class VetoExecPolicy:

VetoExecPolicy defines the policy for blocking or auditing executable execution in environments.

action: Optional[KernelControlsAction]

action specifies what action kernel-level controls take on policy violations

One of the following:
"KERNEL_CONTROLS_ACTION_UNSPECIFIED"
"KERNEL_CONTROLS_ACTION_BLOCK"
"KERNEL_CONTROLS_ACTION_AUDIT"
enabled: Optional[bool]

enabled controls whether executable blocking is active

executables: Optional[List[str]]

executables is the list of executable paths or names to block

class PolicyRetrieveResponse:
agent_policy: AgentPolicy

agent_policy contains agent-specific policy settings

command_deny_list: List[str]

command_deny_list contains a list of commands that agents are not allowed to execute

mcp_disabled: bool

mcp_disabled controls whether MCP (Model Context Protocol) is disabled for agents

scm_tools_disabled: bool

scm_tools_disabled controls whether SCM (Source Control Management) tools are disabled for agents

conversation_sharing_policy: Optional[ConversationSharingPolicy]

conversation_sharing_policy controls whether agent conversations can be shared

One of the following:
"CONVERSATION_SHARING_POLICY_UNSPECIFIED"
"CONVERSATION_SHARING_POLICY_DISABLED"
"CONVERSATION_SHARING_POLICY_ORGANIZATION"
max_subagents_per_environment: Optional[int]

max_subagents_per_environment limits the number of non-terminal sub-agents a parent can have running simultaneously in the same environment. Valid range: 0-10. Zero means use the default (5).

formatint32
maximum10
scm_tools_allowed_group_id: Optional[str]

scm_tools_allowed_group_id restricts SCM tools access to members of this group. Empty means no restriction (all users can use SCM tools if not disabled).

allowed_editor_ids: List[str]

allowed_editor_ids is the list of editor IDs that are allowed to be used in the organization

allow_local_runners: bool

allow_local_runners controls whether local runners are allowed to be used in the organization

default_editor_id: str

default_editor_id is the default editor ID to be used when a user doesn’t specify one

default_environment_image: str

default_environment_image is the default container image when none is defined in repo

maximum_environments_per_user: str

maximum_environments_per_user limits total environments (running or stopped) per user

maximum_running_environments_per_user: str

maximum_running_environments_per_user limits simultaneously running environments per user

members_create_projects: bool

members_create_projects controls whether members can create projects

members_require_projects: bool

members_require_projects controls whether environments can only be created from projects by non-admin users

organization_id: str

organization_id is the ID of the organization

formatuuid
port_sharing_disabled: bool

port_sharing_disabled controls whether user-initiated port sharing is disabled in the organization. System ports (VS Code Browser, agents) are always exempt from this policy.

require_custom_domain_access: bool

require_custom_domain_access controls whether users must access via custom domain when one is configured. When true, access via app.gitpod.io is blocked.

restrict_account_creation_to_scim: bool

restrict_account_creation_to_scim controls whether account creation is restricted to SCIM-provisioned users only. When true and SCIM is configured for the organization, only users provisioned via SCIM can create accounts.

delete_archived_environments_after: Optional[str]

delete_archived_environments_after controls how long archived environments are kept before automatic deletion. 0 means no automatic deletion. Maximum duration is 4 weeks (2419200 seconds).

formatregex
editor_version_restrictions: Optional[Dict[str, EditorVersionRestrictions]]

editor_version_restrictions restricts which editor versions can be used. Maps editor ID to version policy, editor_version_restrictions not set means no restrictions. If empty or not set for an editor, we will use the latest version of the editor

allowed_versions: Optional[List[str]]

allowed_versions lists the versions that are allowed If empty, we will use the latest version of the editor

Examples for JetBrains: ["2025.2", "2025.1", "2024.3"]

maximum_environment_lifetime: Optional[str]

maximum_environment_lifetime controls for how long environments are allowed to be reused. 0 means no maximum lifetime. Maximum duration is 180 days (15552000 seconds).

formatregex
maximum_environment_timeout: Optional[str]

maximum_environment_timeout controls the maximum timeout allowed for environments in seconds. 0 means no limit (never). Minimum duration is 30 minutes (1800 seconds). value must be 0s (no limit) or at least 1800s (30 minutes):

this == duration('0s') || this >= duration('1800s')
formatregex
security_agent_policy: Optional[SecurityAgentPolicy]

security_agent_policy contains security agent configuration for the organization. When configured, security agents are automatically deployed to all environments.

crowdstrike: Optional[CrowdStrikeConfig]

crowdstrike contains CrowdStrike Falcon configuration

additional_options: Optional[Dict[str, str]]

additional_options contains additional FALCONCTL_OPT_* options as key-value pairs. Keys should NOT include the FALCONCTL_OPT_ prefix.

cid_secret_id: Optional[str]

cid_secret_id references an organization secret containing the Customer ID (CID).

formatuuid
enabled: Optional[bool]

enabled controls whether CrowdStrike Falcon is deployed to environments

image: Optional[str]

image is the CrowdStrike Falcon sensor container image reference

tags: Optional[str]

tags are optional tags to apply to the Falcon sensor (comma-separated)

veto_exec_policy: Optional[VetoExecPolicy]

veto_exec_policy contains the veto exec policy for environments.

action: Optional[KernelControlsAction]

action specifies what action kernel-level controls take on policy violations

One of the following:
"KERNEL_CONTROLS_ACTION_UNSPECIFIED"
"KERNEL_CONTROLS_ACTION_BLOCK"
"KERNEL_CONTROLS_ACTION_AUDIT"
enabled: Optional[bool]

enabled controls whether executable blocking is active

executables: Optional[List[str]]

executables is the list of executable paths or names to block