Skip to content

Commit fd25909

Browse files
raphaeltmraphaeltm
authored
Document Workspaces (#330)
* Add documentation for workspaces feature and update related sections * Update workspace information in accounts documentation Clarified that personal workspaces cannot have additional members. * Update authentication documentation for workspace ownership Clarify workspace ownership and membership based on GitHub and GitLab organizations. * Clarify billing context in workspaces documentation Updated description of workspaces to clarify billing context.
1 parent e83b06c commit fd25909

File tree

5 files changed

+178
-2
lines changed

5 files changed

+178
-2
lines changed

‎docs/concepts/accounts.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ At the moment, the only way to authenticate with Defang is through GitHub. We pl
2323
Keep in mind that your Defang account is separate from your [cloud provider account](./defang-byoc.md). You will need to authenticate with your cloud provider account separately to deploy services to your own cloud account.
2424
:::
2525

26+
## Workspaces
27+
28+
When you create an account, a personal [workspace](./workspaces.md) is automatically created for you. Workspaces are how Defang organizes teams and manages billing. You can create additional workspaces or use workspaces linked to your GitHub or GitLab organizations. Your personal workspace cannot have any additional members.
29+
30+
For more information, see [Workspaces](./workspaces.md).
31+
2632
## Structure
2733

2834
Your GitHub username will be used as your Defang username. Your Defang username is used to group all your [services](/docs/concepts/services) and generate domains for your services with the following structure:

‎docs/concepts/authentication.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@ defang login
1313

1414
This will prompt you to open a browser and log in to your [Defang account](/docs/concepts/accounts). You can log in using [GitHub](https://github.com/) or [GitLab](https://gitlab.com/). We will offer other authentication providers in the future. Once you've logged in, you can close the browser and return to the terminal. You will see a message that you've successfully logged in.
1515

16+
If you authorize Defang to access your GitHub or GitLab organizations, [workspaces](/docs/concepts/workspaces) will be automatically created for each organization you have access to. Membership to this workspace will be automatically determined based on membership in the corresponding GitHub and GitLab organizations. The first person to login with a given organization will be made the owner. We will be providing a pathway to transfer ownership in the future.
17+
1618
:::tip
1719
Keep in mind that your Defang account is separate from your [cloud provider account](/docs/concepts/defang-byoc). You will need to authenticate with your cloud provider account separately to deploy services to your own cloud account.
1820
:::

‎docs/concepts/portal.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ description: You can log into the Defang Portal to view the state of your Defang
77

88
You can log into the Defang Portal at [portal.defang.dev](https://portal.defang.dev) using your [Defang account](./accounts.md) to view the state of your Defang services running in the Defang Playground for non-production applications.
99

10-
You can use the Portal to get an overview of your [services](/docs/concepts/services), view the logs for each service, quickly access exposed ports, view environment variables, and more.
10+
You can use the Portal to get an overview of your [services](/docs/concepts/services), view the logs for each service, quickly access exposed ports, view environment variables, and more. The Portal is also where you manage your [workspaces](./workspaces.md), invite team members, and configure billing.
1111

1212
:::info
1313
The Defang Portal displays services deployed to Defang Playground.

‎docs/concepts/workspaces.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Workspaces
3+
description: Workspaces organize teams and manage billing for Defang deployments.
4+
---
5+
6+
# Workspaces
7+
8+
Workspaces are the primary way to organize teams and manage billing in Defang. A workspace represents a billing context that can be shared among team members, allowing multiple developers to deploy services under a team subscription.
9+
10+
## Types of Workspaces
11+
12+
Defang supports three types of workspaces:
13+
14+
### Personal Workspace
15+
16+
When you create a Defang account, a personal workspace is automatically created using your username. This workspace:
17+
18+
- Cannot be deleted
19+
- Cannot have additional members
20+
- Is always available as your default workspace
21+
- Can have a subscription attached for individual use
22+
23+
### Defang-Managed Workspaces
24+
25+
You can create additional workspaces directly in the [Defang Portal](./portal.md). These workspaces:
26+
27+
- Can be renamed or deleted by the owner
28+
- Support inviting team members via invite links
29+
- Allow full membership management within Defang
30+
31+
### Provider-Managed Workspaces
32+
33+
When you log in with GitHub or GitLab and authorize Defang to access your organizations, workspaces are automatically created for each authorized organization. These workspaces:
34+
35+
- Cannot be deleted (the organization must be disconnected from Defang)
36+
- Cannot have members directly invited: membership is managed through your Git provider
37+
- The user who initially connects the organization becomes the workspace owner with billing access
38+
39+
:::info
40+
Ownership transfer for provider-managed workspaces is not yet implemented. The user who connects an organization remains the billing contact.
41+
:::
42+
43+
## Creating a Workspace
44+
45+
To create a Defang-managed workspace:
46+
47+
1. Log in to the [Defang Portal](https://portal.defang.dev)
48+
2. Click the workspace switcher dropdown in the navigation bar
49+
3. Click **Create Workspace** at the bottom of the dropdown
50+
4. Enter a name (lowercase kebab-case is recommended, e.g., `my-team`)
51+
5. Optionally add teammates and select a billing plan
52+
53+
Workspace names are unique and can be changed later. While the portal encourages kebab-case naming for compatibility with CLI usage, the name is stored as entered.
54+
55+
## Using Workspaces with the CLI
56+
57+
### Specifying a Workspace
58+
59+
You can specify which workspace to use for any CLI command using the `--workspace` flag:
60+
61+
```bash
62+
defang compose up --workspace=my-team
63+
```
64+
65+
Alternatively, set the `DEFANG_WORKSPACE` environment variable:
66+
67+
```bash
68+
export DEFANG_WORKSPACE=my-team
69+
defang compose up
70+
```
71+
72+
:::tip
73+
Workspaces can be specified by name or ID. Both work interchangeably.
74+
:::
75+
76+
### Listing Workspaces
77+
78+
To see all workspaces you have access to:
79+
80+
```bash
81+
defang workspace ls
82+
```
83+
84+
Add `--verbose` to include workspace IDs, or `--json` for JSON output.
85+
86+
### Viewing Current Workspace
87+
88+
The `defang whoami` command shows your current workspace:
89+
90+
```bash
91+
defang whoami
92+
```
93+
94+
## Workspace Membership
95+
96+
### Defang-Managed Workspaces
97+
98+
For workspaces created in the Defang Portal:
99+
100+
1. The workspace owner can generate an invite link from the **Invites** tab
101+
2. Share the link with team members
102+
3. When a user clicks the link, they request access
103+
4. The owner approves or denies the request from the portal
104+
105+
Members can have different roles:
106+
- **Owner**: Full control including billing, settings, and member management
107+
- **Admin**: Can manage members and settings
108+
- **Member**: Can use the workspace subscription for deployments
109+
- **Billing**: Can manage payment and subscription details
110+
111+
### Provider-Managed Workspaces
112+
113+
For workspaces created from GitHub or GitLab organizations, membership is managed entirely through your Git provider:
114+
115+
- Add users to the organization in GitHub/GitLab to grant them workspace access
116+
- Remove users from the organization to revoke workspace access
117+
- Changes sync automatically when users log in to Defang
118+
119+
## How Workspaces Relate to Projects
120+
121+
Workspaces provide access to _features_ (deployment capabilities, subscriptions) rather than to specific _projects_. This means:
122+
123+
- Any developer with access to both a workspace (with an active subscription) and a codebase can deploy that code
124+
- If a developer changes workspaces, they can continue deploying the same project using a different workspace's subscription
125+
- The deployment itself lives in the configured cloud account, independent of which workspace was used
126+
127+
:::warning
128+
Deployment logs and history are associated with the workspace used at deployment time. If you deploy a project with Workspace A, then later deploy the same project with Workspace B, the deployment record will be stored under Workspace B.
129+
:::
130+
131+
## CI/CD Integration
132+
133+
When deploying from GitHub Actions using OIDC authentication, the repository owner automatically becomes the tenant context. This allows CI/CD pipelines to deploy without explicitly specifying a workspace, as long as the repository owner has an active subscription.
134+
135+
For more details, see [Deploying from GitHub Actions](/docs/tutorials/deploying-from-github-actions).

0 commit comments

Comments
 (0)