This pull request updates the authentication documentation for
`fabric-cicd` to deprecate the use of `DefaultAzureCredential` and
provide clear migration guidance to explicit credential methods. It
introduces a deprecation warning, reorganizes and clarifies
authentication examples, and adds guidance for using explicit credential
flows including Azure CLI, Azure PowerShell, and Managed Identity. The
changes emphasize security best practices and provide updated code
samples for different environments.
**Deprecation and migration guidance:**
* Added a deprecation warning for the use of `DefaultAzureCredential`,
advising users to migrate to explicit credential methods and providing
migration guidance in the documentation.
(`.changes/unreleased/optimization-20260325-161506.yaml`)
* Updated the authentication documentation to highlight the deprecation
and removal of the default credential flow, and clarified that explicit
`token_credential` parameters should be used in all scenarios except
Fabric Notebook runtime. (`docs/example/authentication.md`)
**Expanded and improved credential examples:**
* Replaced the default credential examples with explicit code samples
for Azure CLI (`AzureCliCredential`), Azure PowerShell
(`AzurePowerShellCredential`), and Managed Identity
(`ManagedIdentityCredential`) authentication flows, including updated
guidance and environment-specific instructions for local, Azure DevOps,
and GitHub Actions scenarios. (`docs/example/authentication.md`)
[[1]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eR35-R44)
[[2]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL46-R66)
[[3]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eR86-R95)
[[4]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL91-R136)
[[5]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL141-R157)
[[6]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL164-R170)
[[7]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL187-R200)
[[8]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL215-R221)
[[9]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL237-R261)
[[10]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eR280-R296)
[[11]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL320-R317)
[[12]](diffhunk://#diff-209795f61181441c3bebe319157e9b2dec863d464945eb609858eec490c73a9eL343-R358)
**Security and best practices:**
* Added notes advising against hardcoding credentials and recommended
using environment variables or secret management services, with specific
guidance for SPN + Secret authentication via CLI or PowerShell.
(`docs/example/authentication.md`)
These changes ensure users follow security best practices and have
clear, up-to-date examples for authenticating with `fabric-cicd` in a
variety of environments.
---------
Co-authored-by: Shira Sassoon <shirasassoon@microsoft.com>
## Description
Adds comprehensive troubleshooting documentation for users debugging
deployments and contributors developing within the repository. Addresses
the gap in documenting debugging tools, error logs, API traces, and
development utilities.
### Key Changes
- **New troubleshooting guide** (`docs/how_to/troubleshooting.md`):
- **User debugging**: `change_log_level()` usage,
`fabric_cicd.error.log` contents, API trace access, common deployment
issues with solutions
- **Contributor tools**: Complete documentation for all `devtools/`
scripts:
- `debug_local.py` - Full deployment workflow testing
- `debug_local config.py` - Config-based deployment testing
- `debug_parameterization.py` - Parameter file validation
- `debug_api.py` - Direct Fabric REST API testing
- `pypi_build_release_dev.ps1` - TestPyPI package testing
- Testing guidance and debug output instructions
- **Navigation update**: Added troubleshooting to `mkdocs.yml` under
"How To" section
- **Cross-reference**: Updated `optional_feature.md` debugging section
to link to comprehensive guide
### Usage Example
Enable debug logging to capture detailed API traces:
```python
from fabric_cicd import change_log_level
# Enable debug logging before workspace operations
change_log_level("DEBUG")
# All API calls and errors now logged to fabric_cicd.error.log
target_workspace = FabricWorkspace(...)
publish_all_items(target_workspace)
```
### Screenshots
Full troubleshooting guide page:
<img
src="https://github.com/user-attachments/assets/537c14d8-6285-450a-91e9-82bf00731725">
Documentation for debug_api.py:
<img
src="https://github.com/user-attachments/assets/1dc967cb-5c05-4b37-a16a-95041f474755">
## Linked Issue (REQUIRED)
Issue linking handled via PR title format.
<!-- START COPILOT ORIGINAL PROMPT -->
<details>
<summary>Original prompt</summary>
>
> ----
>
> *This section details on the original issue you should resolve*
>
> <issue_title>Add Troubleshooting Guide Documentation</issue_title>
> <issue_description>### URL to documentation
>
> N/A
>
> ### Feedback
>
> fabric-cicd is missing documented TSG or general debugging guide for
end users interacting with the tool or developing within the repository.
>
> As a user of the library, it is unclear as to what tools can be used
within fabric-cicd to debug issues with my deployment. Also, as a
contributor it is unclear what tools can be used to test my code before
merging with main.
> I noticed there is a folder that sits in the fabric-cicd repository
that is called devtools which contain various files that can be used for
debugging. Provide a clear description for each file, including its
intended purpose and common use cases.
> There is also a log level change feature which can be used to view
logs during deployment, I think customers are not aware of this valuable
tool and super helpful for debugging.
> Lastly, when it comes to understanding the cause of an issue during
deployment a trace of the API call would clarify if it were indeed
caused by an API issue. Let’s add more context on how these traces can
be accessed from fabric-cicd through the fabric_cicd error log.
>
>
> ### Additional context
>
> _No response_</issue_description>
>
> ## Comments on the Issue (you are @copilot in this section)
>
> <comments>
> </comments>
>
</details>
<!-- START COPILOT CODING AGENT SUFFIX -->
- Fixesmicrosoft/fabric-cicd#705
<!-- START COPILOT CODING AGENT TIPS -->
---
💬 We'd love your input! Share your thoughts on Copilot coding agent in
our [2 minute survey](https://gh.io/copilot-coding-agent-survey).
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: shirasassoon <66449905+shirasassoon@users.noreply.github.com>
Co-authored-by: Shira Sassoon <shirasassoon@microsoft.com>
shirasassoonandShira Sassoon
