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 --treeNAME SLUG
Engineering/ fld_a1b2c3d4e5f6
Payments/ fld_b2c3d4e5f6a1
payments-prod prj_c3d4e5f6a1b2
ops prj_d4e5f6a1b2c3ezgh 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.
- Open Projects and click Create folder.
- Enter a Name and choose a Location.
- Click Create folder.
ezgh folders create Engineering
ezgh folders create Payments --parent Engineeringcurl -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 BillingThe 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.