Folders, projects and environments

A folder groups apps in the overview and can be shared with a member at a capability level that differs from their team role. A project groups apps and databases and holds environments (production, staging, whatever you call them), the boundary environment variables and previews respect. Filing an app into a folder clears its project link, so most apps live in one or the other.

Folders

folders

Any signed-in principal. Returns [Folder!].

All folders in the active team, in display order.

query {
  folders {
    id
    name
    parentId
    appCount
  }
}

createFolder

Needs create_folders. Returns Folder.

Create a folder in the active team; nest it by passing a parent folder id. Requires the create_folders capability; the creator becomes the folder's owner.

mutation {
  createFolder(name: "shop") {
    id
    name
    parentId
    appCount
  }
}

renameFolder

Any signed-in principal. Returns Boolean.

Rename a folder.

mutation {
  renameFolder(id: "fld_9f1c2ab7d3e4f5a6", name: "shop")
}

setFolderColor

Any signed-in principal. Returns Boolean.

Set a folder's accent colour (hex, e.g. #3b82f6), or clear it back to the default when color is omitted/null.

mutation {
  setFolderColor(id: "fld_9f1c2ab7d3e4f5a6")
}

moveFolder

Any signed-in principal. Returns Boolean.

Move a folder under a new parent folder, or to the top level when parentId is omitted/null. Rejects moving a folder into itself or a descendant.

mutation {
  moveFolder(id: "fld_9f1c2ab7d3e4f5a6")
}

reorderFolders

Needs manage_team, or instance admin. Returns Boolean.

Set the team-wide display order of folders in Overview.

mutation {
  reorderFolders(folderIds: [["fld_9f1c2ab7d3e4f5a6"]])
}

deleteFolder

Any signed-in principal. Returns Boolean.

Delete a folder; its apps fall back to the top level, or are stopped and deleted with it when deleteApps is true (which needs delete_apps on every one of them).

mutation {
  deleteFolder(id: "fld_9f1c2ab7d3e4f5a6", deleteApps: false)
}

Folder sharing

A grant is bounded by both the granter's and the grantee's capabilities. Only the folder's owner or a team admin may hand one out.

folderGrants

Any signed-in principal. Returns [FolderGrant!].

Who can access a folder - its owner plus every user it's shared with. Owner/admin only.

query {
  folderGrants(folderId: "fld_9f1c2ab7d3e4f5a6") {
    userId
    username
    capabilities
    isOwner
  }
}

folderShareCandidates

Any signed-in principal. Returns [FolderShareCandidate!].

Team members who could be granted access to a folder (not the owner, not already granted). Owner/admin only.

query {
  folderShareCandidates(folderId: "fld_9f1c2ab7d3e4f5a6") {
    userId
    username
    name
  }
}

grantableFolderCapabilities

Any signed-in principal. Returns [String!].

The capabilities the caller may hand out on a folder (their own effective folder caps). Owner/admin only.

query {
  grantableFolderCapabilities(folderId: "fld_9f1c2ab7d3e4f5a6")
}

setFolderGrant

Any signed-in principal. Returns [FolderGrant!].

Grant (or replace) a user's capabilities on a folder. Bounded by both the granter's and the grantee's caps; owner/admin only. Returns the fresh grant list.

mutation {
  setFolderGrant(folderId: "fld_9f1c2ab7d3e4f5a6", userId: "user_9f1c2ab7d3e4f5a6", capabilities: ["deploy_apps", "view_logs"]) {
    userId
    capabilities
  }
}

removeFolderGrant

Any signed-in principal. Returns [FolderGrant!].

Revoke a user's access to a folder. Owner/admin only. Returns the fresh grant list.

mutation {
  removeFolderGrant(
    folderId: "fld_9f1c2ab7d3e4f5a6"
    userId: "user_9f1c2ab7d3e4f5a6"
  ) {
    userId
    username
    capabilities
    isOwner
  }
}

Projects

projects

Any signed-in principal. Returns [Project!].

All Project containers in the active team, in display order.

query {
  projects {
    id
    slug
    name
    environmentCount
  }
}

project

Any signed-in principal. Returns Project.

A single Project container by its team-scoped slug, or null.

query {
  project(slug: "shop") {
    id
    slug
    name
    environmentCount
  }
}

createProject

Needs create_projects. Returns Project.

Create a Project container in the active team. Requires deploy; the creator becomes its owner.

mutation {
  createProject(name: "shop") {
    id
    slug
    name
    environmentCount
  }
}

renameProject

Needs organize_projects. Returns Boolean.

Rename a Project container.

mutation {
  renameProject(id: "prc_9f1c2ab7d3e4f5a6", name: "shop")
}

setProjectColor

Needs organize_projects. Returns Boolean.

Set a Project container's accent colour (hex), or clear it when color is omitted/null.

mutation {
  setProjectColor(id: "prc_9f1c2ab7d3e4f5a6")
}

reorderProjects

Needs manage_team, or instance admin. Returns Boolean.

Set the team-wide display order of Project containers.

mutation {
  reorderProjects(projectIds: [["prc_9f1c2ab7d3e4f5a6"]])
}

deleteProject

Needs delete_projects. Returns Boolean.

Delete a Project container; its folders and apps fall back to the team top level, or every app inside is stopped and deleted with it when deleteApps is true (which needs delete_apps on every one of them).

mutation {
  deleteProject(id: "prc_9f1c2ab7d3e4f5a6", deleteApps: false)
}

Environments

environments

Any signed-in principal. Returns [Environment!].

The environments of a Project container, in display order.

query {
  environments(projectId: "prc_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    isDefault
    gitBranch
  }
}

createEnvironment

Needs manage_environments. Returns Environment.

Add a custom environment to a Project container.

mutation {
  createEnvironment(name: "shop", projectId: "prc_9f1c2ab7d3e4f5a6") {
    id
    slug
    name
    isDefault
    gitBranch
  }
}

renameEnvironment

Needs manage_environments. Returns Boolean.

Rename an environment.

mutation {
  renameEnvironment(id: "environ_9f1c2ab7d3e4f5a6", name: "shop")
}

setDefaultEnvironment

Needs manage_environments. Returns Boolean.

Make an environment the project's default (unsets the previous one).

mutation {
  setDefaultEnvironment(id: "environ_9f1c2ab7d3e4f5a6")
}

setEnvironmentBranch

Needs manage_environments. Returns Boolean.

Set the git branch an environment builds from (empty => the app's default branch).

mutation {
  setEnvironmentBranch(branch: "main", id: "environ_9f1c2ab7d3e4f5a6")
}

deleteEnvironment

Needs manage_environments. Returns Boolean.

Delete a non-default environment (never the default or the last remaining one).

mutation {
  deleteEnvironment(id: "environ_9f1c2ab7d3e4f5a6")
}

Moving apps and databases

moveAppToFolder

Any signed-in principal. Returns Boolean.

Move an app into a folder, or back to the top level when folderId is omitted/null.

mutation {
  moveAppToFolder(appId: "prj_9f1c2ab7d3e4f5a6")
}

moveAppsToFolder

Any signed-in principal. Returns Int.

Bulk-move several apps into a folder (or to the top level when folderId is omitted/null) in one write. Returns how many moved.

mutation {
  moveAppsToFolder(appIds: [["prj_9f1c2ab7d3e4f5a6"]])
}

moveAppToProject

Needs move_apps. Returns Boolean.

Move an app into a Project (landing in its default environment), or back to the top level when projectId is omitted/null.

mutation {
  moveAppToProject(appId: "prj_9f1c2ab7d3e4f5a6")
}

moveAppToEnvironment

Needs move_apps. Returns Boolean.

Move an app into a specific environment of a project. Each environment holds its own apps, so the app's project follows the environment.

mutation {
  moveAppToEnvironment(
    appId: "prj_9f1c2ab7d3e4f5a6"
    environmentId: "environ_9f1c2ab7d3e4f5a6"
  )
}

moveDatabaseToEnvironment

Needs configure_databases. Returns Boolean.

Move a database into an Environment, or out to the team's top level (null). The placement is also the network it answers on, so the container is brought up again on the new one before this returns - an app reaches db-<slug> only from the same Environment.

mutation {
  moveDatabaseToEnvironment(id: "db_9f1c2ab7d3e4f5a6", environmentId: "environ_9f1c2ab7d3e4f5a6")
}

See also