Task 02 - Troubleshoot your GitHub Actions workflow

Introduction

Having created a GitHub Actions workflow, you may encounter issues as you test it. This exercise will help you navigate the troubleshooting steps.

Description

In this task you will learn how to troubleshoot common issues with your GitHub Actions workflow.

Success Criteria

  • You will successfully fix any issues with your workflow
  • You will learn important tips for troubleshooting your workflow

Key Tasks

After deployment, the app may still fail to load correctly even if the workflow succeeds. This is normal — AI systems and cloud environments are non-deterministic, and runtime errors can vary across different configurations and deployments. The following steps show various potential issues and tips to resolve them.

01: Authentication Failures

Troubleshoot Azure authentication failures that occur when the login step fails or you encounter authentication errors.

Expand this section for detailed troubleshooting steps

Symptoms:

  • Azure login step fails
  • Error messages like “AADSTS70002” or “invalid_client”

Troubleshooting Steps:

  1. Verify Secret Configuration 
    # Check that AZURE_CREDENTIALS secret exists
# Go to Settings → Secrets and variables → Actions → Secrets
  2. Validate Service Principal JSON
    • Ensure the JSON format is correct (in your saved copy, you won’t be able to see it in GitHub)
    • Verify all required fields are present: clientId, clientSecret, subscriptionId, tenantId
  3. Test Service Principal Locally 
    az login --service-principal -u <clientId> -p <clientSecret> --tenant <tenantId>

02: Variable Configuration Issues

Resolve issues where variables are empty, undefined, or incorrectly configured in your GitHub Actions workflow.

Expand this section for detailed troubleshooting steps

Symptoms:

  • Variables show as empty or undefined
  • Container registry login fails
  • App Service not found errors

Troubleshooting Steps:

  1. Verify All Variables Exist
    • Go to Settings → Secrets and variables → Actions → Variables
    • Confirm all required variables are present:
      • AZURE_CONTAINER_REGISTRY
      • AZURE_CONTAINER_REGISTRY_NAME
      • AZURE_APP_SERVICE_NAME
      • AZURE_RESOURCE_GROUP
  2. Validate Variable Values 
    # List your actual Azure resources to verify names
az resource list --resource-group <your-resource-group> --output table
  3. Check for Typos
    • Ensure variable names match exactly between workflow YAML and GitHub settings
    • Verify resource names are spelled correctly

03: Docker Build/Push Failures

Fix Docker build and push failures that occur during the container image creation and registry upload process.

Expand this section for detailed troubleshooting steps

Symptoms:

  • Docker build step fails
  • “no such file or directory” errors
  • Push to registry fails

Troubleshooting Steps:

  1. Verify Dockerfile Location
    • Ensure Dockerfile exists in the src/ directory
    • Check the cd src/ command in the workflow
  2. Test Docker Build Locally 
    cd src/
docker build -t test-image .
  3. Check Container Registry Permissions
    • Verify the service principal has push permissions to ACR 
      az acr check-health --name <your-acr-name>

04: Azure App Service Deployment Issues

Resolve deployment issues where the workflow succeeds but the application fails to load or respond correctly.

Expand this section for detailed troubleshooting steps

Symptoms:

  • Deployment step succeeds but app doesn’t respond
  • 502/504 gateway errors
  • App service shows “Application Error”

Troubleshooting Steps:

  1. Check App Service Configuration 
    az webapp config show --name <your-app-name> --resource-group <your-rg>
  2. Review App Service Logs 
    az webapp log tail --name <your-app-name> --resource-group <your-rg>
  3. Verify Container Settings
    • Ensure WEBSITES_PORT matches your app’s listening port
    • Check that acrUseManagedIdentityCreds is set correctly

05: Using GitHub Copilot for Troubleshooting

Leverage GitHub Copilot Chat to help diagnose and resolve workflow failures by providing error context and workflow details.

Expand this section for detailed steps

If your workflow fails, you can leverage GitHub Copilot Chat for assistance:

  1. Copy Error Messages
    • Copy the relevant error messages from the workflow logs
    • Include context about which step failed
  2. Ask Copilot for Help 
    My GitHub Actions workflow is failing with this error:
[paste error message here]

The failure occurs during the [step name] step. Can you help me diagnose and fix this issue?
  3. Provide Additional Context 
    Here's my workflow YAML:
[paste relevant workflow sections]

And here are my repository variables:
- AZURE_CONTAINER_REGISTRY: [value]
- AZURE_APP_SERVICE_NAME: [value]

Summary

You’ve completed this task. You have successfully fixed any issues with your workflow and learned important tips for troubleshooting your workflow.