Skip to content

Commit 39aa30e

Browse files
author
Aviat Cohen
committed
deploy documentation
1 parent 264bdbc commit 39aa30e

File tree

1 file changed

+224
-0
lines changed

1 file changed

+224
-0
lines changed

‎docs/commands/fs/deploy.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# `deploy` Command
2+
3+
Deploy a Fabric workspace from local source content into a target Microsoft Fabric workspace.
4+
5+
---
6+
7+
## Description
8+
9+
The `deploy` command imports workspace content from a local source into a target Fabric workspace.
10+
11+
You can deploy:
12+
- an entire workspace
13+
- specific folders
14+
- specific items
15+
16+
The scope and behavior of the deployment are defined entirely by the deployment configuration file.
17+
18+
During execution, the command:
19+
- publishes items found in the source into the target workspace
20+
- resolves dependencies between items automatically when logical IDs are present
21+
- removes items from the target workspace that no longer exist in the source (unpublish)
22+
23+
By default, **both publish and unpublish operations are enabled and executed**.
24+
To disable either operation for a specific environment, it must be explicitly skipped in the configuration file.
25+
26+
The deployment is executed directly against Fabric workspaces using Fabric APIs.
27+
28+
---
29+
30+
## Usage
31+
32+
```bash
33+
fab deploy --config <config_file> [--target_env <environment>] [--params <parameters>] [--force]
34+
```
35+
36+
---
37+
38+
## Options
39+
40+
| Option | Description |
41+
|------|-------------|
42+
| `--config <file>` | Path to the deployment configuration file. **Required**. |
43+
| `--target_env, -tenv <env>` | Environment name used to select environment-specific settings from the configuration file. |
44+
| `--params, -P <params>` | JSON-formatted parameters provided to the deployment process at runtime. |
45+
| `--force, -f` | Run the deployment without interactive confirmation prompts. |
46+
| `--help` | Show detailed help for the `deploy` command. |
47+
48+
---
49+
50+
## Configuration Behavior
51+
52+
- The configuration file controls what is published and unpublished.
53+
- Publish and unpublish operations are enabled by default.
54+
- Skipping publish or unpublish must be explicitly defined per environment.
55+
- Environment selection is resolved only when environment mappings are present in the configuration.
56+
- If `--target_env` is not specified, the configuration must not contain environment-specific mappings.
57+
58+
---
59+
60+
## Configuration File
61+
62+
### Minimal Configuration (No Environments)
63+
64+
```yaml
65+
core:
66+
workspace_id: "12345678-1234-1234-1234-123456789abc"
67+
repository_directory: "."
68+
```
69+
70+
---
71+
72+
### Configuration Fields
73+
74+
| Field | Description | Mandatory |
75+
|------|------------|-----------|
76+
| `core.workspace_id` | Target workspace ID (GUID). Takes precedence over `workspace`. | ✅ Yes |
77+
| `core.workspace` | Target workspace name. Alternative to `workspace_id`. | ❌ No |
78+
| `core.repository_directory` | Path to local directory containing workspace content. | ✅ Yes |
79+
| `core.item_types_in_scope` | List of item types included in deployment. | ❌ No |
80+
| `core.parameter` | Path to parameter file. | ❌ No |
81+
| `publish` | Controls publishing behavior. | ❌ No |
82+
| `unpublish` | Controls unpublishing behavior. | ❌ No |
83+
| `features` | Feature flags. | ❌ No |
84+
| `constants` | API constant overrides. | ❌ No |
85+
86+
Relative paths are resolved relative to the configuration file location.
87+
88+
---
89+
90+
## Publish and Unpublish Settings
91+
92+
### Publish
93+
94+
```yaml
95+
publish:
96+
exclude_regex: "^DONT_DEPLOY.*" # Excludes items matching this pattern from publishing
97+
folder_exclude_regex: "^legacy/" # Excludes items under matching folders from publishing
98+
items_to_include: # Publishes only the specified items (requires feature flags)
99+
- "MainNotebook.Notebook"
100+
skip: # Skips publishing per environment
101+
dev: true
102+
test: false
103+
prod: false
104+
```
105+
106+
### Unpublish
107+
108+
```yaml
109+
unpublish:
110+
exclude_regex: "^DEBUG.*" # Prevents matching items from being removed
111+
items_to_include: # Unpublishes only the specified items (requires feature flags)
112+
- "OldPipeline.DataPipeline"
113+
skip: # Skips unpublishing per environment
114+
dev: true
115+
test: false
116+
prod: false
117+
```
118+
119+
> **Note**
120+
> While selective deployment is supported, it is not recommended due to potential issues with dependency management. Use selective deployment options with caution.
121+
122+
---
123+
124+
## Parameter File
125+
126+
The parameter file enables environment-specific transformation of deployed content.
127+
128+
It can be used to:
129+
- replace workspace and item identifiers
130+
- replace connection strings and URLs
131+
- update embedded values inside item definitions
132+
- parameterize environment-specific configuration values
133+
134+
The parameter file is optional and is applied only when specified in the configuration.
135+
136+
When items were exported or created using Fabric CLI (and not through Git integration), dependencies must be explicitly defined in the parameter file to ensure correct resolution during deployment.
137+
138+
### Example
139+
140+
```yaml
141+
find_replace:
142+
- find_value: "dev-connection-string"
143+
replace_value:
144+
dev: "dev-connection-string"
145+
test: "test-connection-string"
146+
prod: "prod-connection-string"
147+
```
148+
149+
### Supported Variables
150+
151+
- `$workspace.$id` — resolves to the target workspace ID
152+
- `$items.<ItemType>.<ItemName>.$id` — resolves to the deployed item ID
153+
154+
Parameterization behavior follows the documented model described here:
155+
156+
https://microsoft.github.io/fabric-cicd/0.1.3/how_to/parameterization/add
157+
158+
---
159+
160+
## Examples
161+
162+
### Basic Deployment
163+
164+
```bash
165+
fab deploy --config config.yml
166+
```
167+
168+
### Deployment to a Specific Environment
169+
170+
```bash
171+
fab deploy --config config.yml --target_env prod
172+
```
173+
174+
### Deployment with Runtime Parameters
175+
176+
```bash
177+
fab deploy --config config.yml --target_env test -P '{"core":{"item_types_in_scope":["Notebook"]}}'
178+
```
179+
180+
---
181+
182+
## Preparing Source Content
183+
184+
### Using Git Integration
185+
186+
If the workspace is connected to Git, clone the repository locally:
187+
188+
```bash
189+
git clone https://github.com/org/fabric-workspace.git
190+
```
191+
192+
Use the cloned repository as the deployment source.
193+
194+
---
195+
196+
### Using `fab export`
197+
198+
`fab export` exports one item at a time and does not include logical IDs.
199+
200+
```bash
201+
fab export --output ./path-to-ws MyDataPipeline.DataPipeline --format .py
202+
```
203+
204+
To export Notebook items use the `--format .py` option.
205+
206+
```bash
207+
fab export --output ./path-to-ws MyNotebook.Notebook --format .py
208+
```
209+
210+
---
211+
212+
## Notes
213+
214+
- `fab deploy` does not require Git integration; however, using Git integration is strongly recommended to ensure dependencies.
215+
- The deploy command supports content sourced from Git repositories, locally exported items, and items created locally.
216+
- Specifying a target environment is optional. If --target_env is provided, only values for that environment are applied. If environment‑specific values exist in the configuration, --target_env is required.
217+
- Parameter files are optional and apply to all deployment scenarios.
218+
219+
---
220+
221+
## Related Commands
222+
223+
- `export` — Export individual items from a workspace
224+
- `import` — Import individual items into a workspace

0 commit comments

Comments
 (0)