Skip to content

Folders

Group projects in folders, and nest folders up to 5 levels deep.

Updated View as Markdown

Folders group an organization’s projects and other folders. They only organize:

  • A folder gives nobody access. No policy reaches a project through its folder, and moving a project or folder changes nobody’s access.
  • A project’s resource name never includes its folder, so moving it changes no resource names.
  • Folders nest at most 5 levels deep: a folder at the top of the organization is level 1.
  • A folder’s name is unique among the folders in the same place, ignoring case.
  • Only an empty folder can be deleted.

Identifiers

Field Example Notes
id 0199a3c5-1b2c-7d3e-8f40-5a6b7c8d9e0f UUID. API paths and bodies use it.
slug fld_a1b2c3d4e5f6 fld_ and 12 lowercase letters and digits. Generated, unique and never changes.
resourceName ezgh::org_k3f9a0x2m7qp:fld_a1b2c3d4e5f6 Names the folder in IAM policies, for the folders.* actions.
name Payments 1 to 100 characters.
parentId 0199a3c5-… or null The folder it sits in; null at the top of the organization.

A project’s folderId is the folder it sits in, or null at the top of the organization.

The ezgh CLI accepts a folder’s ID, slug, name, or path from the top of the organization, such as Engineering/Payments.

Permissions

Action Allows Checked against
folders.list Listing folders. A list shows the folders you’re allowed to list. Folder
folders.get Viewing a folder Folder
folders.create Creating folders Organization
folders.update Renaming and moving folders Folder
folders.delete Deleting empty folders Folder

BasicAccess and ReadOnlyAccess include folders.list and folders.get, so people can see the folders their projects sit in. ProjectsFullAccess includes every folders.* action. Moving a project needs only projects.update on the project.

See folders and projects

Open Projects. Folders and projects show as one tree: expand a folder to see what it holds. The filter matches folder and project names and IDs, and shows each match with the folders above it.

ezgh projects list --tree
NAME                SLUG
Engineering/        fld_a1b2c3d4e5f6
  Payments/         fld_b2c3d4e5f6a1
    payments-prod   prj_c3d4e5f6a1b2
ops                 prj_d4e5f6a1b2c3

ezgh folders list lists folders one page at a time, with the folder each sits in.

curl https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders \
  -H "Authorization: Bearer $EZGH_API_KEY"

The response is { "folders": [...], "nextCursor": ... }, paged like other lists. See ListFolders and GetFolder.

Create a folder

You need folders.create. Leave out the parent to create the folder at the top of the organization.

  1. Open Projects and click Create folder.
  2. Enter a Name and choose a Location.
  3. Click Create folder.
ezgh folders create Engineering
ezgh folders create Payments --parent Engineering
curl -X POST https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Payments", "parentId": "'$PARENT_FOLDER_ID'" }'

The response is 201 with the folder. See CreateFolder and idempotency keys.

Rename or move a folder

You need folders.update on the folder. A folder moves with everything in it. You can’t move a folder into itself or a folder inside it, or make the tree more than 5 levels deep.

Open the folder, then the Settings tab. Change its name and click Rename, or choose another folder under Location and click Move.

ezgh folders update Payments --name Billing
ezgh folders update Billing --parent Finance
ezgh folders update Billing --root

--root moves the folder to the top of the organization.

curl -X PATCH https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders/$FOLDER_ID \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parentId": null }'

Send name, parentId or both. "parentId": null moves the folder to the top of the organization. See UpdateFolder.

Move a project into a folder

See Move a project. To create a project in a folder, see Create a project.

Delete a folder

You need folders.delete on the folder. Only an empty folder can be deleted: move or delete its projects and folders first.

Open the folder, then the Settings tab, and click Delete folder. It’s disabled while the folder holds anything you can see; a folder that holds anything can’t be deleted (409 folder_not_empty).

ezgh folders delete Billing

The CLI asks for confirmation; --yes skips it.

curl -X DELETE https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders/$FOLDER_ID \
  -H "Authorization: Bearer $EZGH_API_KEY"

The response is 204. See DeleteFolder.

Errors

Status Code When
404 not_found The folder or parent doesn’t exist, was deleted, or belongs to another organization.
409 folder_name_taken A folder with that name is already in the same place.
409 folder_too_deep The folder would be more than 5 levels deep.
409 folder_cycle The move would put a folder inside itself or a folder inside it.
409 folder_not_empty The folder still holds a project or folder.
409 quota_exceeded The organization has as many folders as its quota allows.
412 precondition_failed An If-Match on a rename, move or delete doesn’t match the folder’s current ETag. See conditional writes.

Folder quota

An organization can have 100 folders by default. The quota is organizations.folders.count (Folders per organization). It counts folders that exist: deleting one frees its slot. See Service quotas.

Navigation

Type to search…

↑↓ navigate↵ selectEsc close