Add documentation for GitHub Actions working-directory configuration in multi-project solutions

docs/deployment/azure/aca-deployment-github-actions.md

@@ -1,7 +1,7 @@
 ---
 title: Deploy a .NET Aspire project using the Azure Developer CLI
 description: Learn how to use `azd` to deploy .NET Aspire projects.
-ms.date: 01/08/2025
+ms.date: 07/17/2025
 zone_pivot_groups: deployment-platform
 ms.custom: devx-track-extended-azdevcli
 ---
@@ -102,6 +102,81 @@ The Azure Developer CLI enables you to automatically create CI/CD pipelines with
 
 Congratulations! You successfully deployed a .NET Aspire project using the Azure Developer CLI and GitHub Actions.
 
+## Configure working directory for multi-project solutions
+
+When you add GitHub Actions to an existing multi-project .NET Aspire solution where the AppHost project isn't in the root directory, you might need to configure the `working-directory` parameter for certain workflow steps. This section explains when and how to make these adjustments.
+
+### When working-directory configuration is needed
+
+The `azd pipeline config` command generates a GitHub Actions workflow that assumes your .NET Aspire AppHost project is in the root directory of your repository. However, in many real-world scenarios, especially when [adding .NET Aspire to existing applications](../../get-started/add-aspire-existing-app.md), the AppHost project might be in a subdirectory.
+
+For example, if your repository structure looks like this:
+
+```Directory
+└───📂 MyAspireApp
+    ├───📂 MyAspireApp.ApiService
+    ├───📂 MyAspireApp.AppHost
+    │    ├─── MyAspireApp.AppHost.csproj
+    │    └─── Program.cs
+    ├───📂 MyAspireApp.Web
+    └─── MyAspireApp.sln
+```
+
+The generated workflow steps for **Provision Infrastructure** and **Deploy Application** need to run from the `MyAspireApp.AppHost` directory, not from the repository root.
+
+### Updating the GitHub Actions workflow
+
+After running `azd pipeline config`, examine the generated workflow file in `.github/workflows/azure-dev.yml`. Look for steps that run `azd` commands and add the `working-directory` parameter as needed.
+
+Here's an example of the original generated steps:
+
+```yaml
+- name: Provision Infrastructure
+  run: azd provision --no-prompt
+  env:
+    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
+    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
+    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+- name: Deploy Application
+  run: azd deploy --no-prompt
+  env:
+    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
+    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
+    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+```
+
+Update these steps to include the `working-directory` parameter:
+
+```yaml
+- name: Provision Infrastructure
+  run: azd provision --no-prompt
+  working-directory: ./MyAspireApp.AppHost
+  env:
+    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
+    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
+    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+
+- name: Deploy Application
+  run: azd deploy --no-prompt
+  working-directory: ./MyAspireApp.AppHost
+  env:
+    AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
+    AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
+    AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
+```
+
+### Finding the correct working directory
+
+The working directory should point to the folder containing your .NET Aspire AppHost project (the project that contains the _azure.yaml_ file generated by `azd init`). You can identify this directory by:
+
+1. Look for the project with the `Aspire.AppHost` package reference in its `.csproj` file.
+1. Find the directory containing the _azure.yaml_ file.
+1. Locate the project referenced in your solution that orchestrates other services.
+
+> [!NOTE]
+> Some `azd` commands, such as `azd init` during pipeline setup, might also need the `working-directory` parameter if they're not running from the AppHost project directory.
+
 :::zone-end
 
 :::zone pivot="azure-pipelines"
@@ -209,9 +284,9 @@ Add an `azd init` step to your Azure DevOps pipeline before the provisioning ste
 
 Make sure to define the following variables in your pipeline:
 
-- `AZURE_ENV_NAME`: Your environment name (for example, `dev` or `prod`)
-- `AZURE_LOCATION`: Your Azure region (for example, `eastus2`)
-- `AZURE_SUBSCRIPTION_ID`: Your Azure subscription ID
+- `AZURE_ENV_NAME`: Your environment name (for example, `dev` or `prod`).
+- `AZURE_LOCATION`: Your Azure region (for example, `eastus2`).
+- `AZURE_SUBSCRIPTION_ID`: Your Azure subscription ID.
 
 #### Option 2: Commit required files to your repository
 
@@ -230,9 +305,9 @@ Ensure that you run `azd pipeline config --provider azdo` after successfully run
 
 If you continue to experience issues, verify that:
 
-- Your project structure matches what `azd` expects for .NET Aspire projects
-- You're running the commands from the correct directory (typically where your `.sln` file is located)
-- Your Azure DevOps service connection has the necessary permissions for provisioning resources
+- Your project structure matches what `azd` expects for .NET Aspire projects.
+- You're running the commands from the correct directory (typically where your `.sln` file is located).
+- Your Azure DevOps service connection has the necessary permissions for provisioning resources.
 
 :::zone-end