Bug: AzureStaticWebApp + Azure DevOps + Oryx + Hugo: Undocumented magic is witchcraft

[nevi-me]

Hi, please ignore or excuse the title, it describes my situation though.

I'm trying to build a static website (Hugo) to Azure Static Web app, using an Azure Pipeline, because I can't use Github for this (it's a corporate site).

Note: I've spent 2+ hours trying to perform a simple task of deployinh a Hugo website to a static web app, via Azure Pipelines.

I've checked official docs, tutorials, blogs from people; etc. Everything has boiled down to the below:

Summary

Should we be using static-web-apps with Azure Pipelines? I've just had a poor experience with this.

It's great to create abstractions that make customers' lives easier, but when that magic doesn't work; that magic starts to feel like witchcraft.

Unclear what AzureStaticWebApp does

I created a pipeline, with a simple chain of bash scripts to build my hugo website. Those tasks pass, but I was surprised to see my pipeline being built the second time with a Microsoft Oryx.

Cool, I can remove my hugo bash script thing, and rely on this. Handy! I however didn't get a clear sense of this, because most tutorials focus on Github Actions.

Azure Pipelines + Static Web Apps

Literally almost all documentation points one to using SWA with Github Actions.

I understand the popularity, perhaps that the SWA product is meant for people who just want to get a static web thing running in a few minutes, but this product either doesn't work with Azure pipelines, or there's serious documentation gaps.

The above screenshot is me changing a combination of the below:

  - task: AzureStaticWebApp@0
    inputs:
      app_location: "/" 
      app_artifact_location: "public"
      output_location: ""
    env:
      azure_static_web_apps_api_token: $(deployment_token)

Here's what I'm trying to express:

• I'm using a Hugo website (detected)
• I haven't changed any configuration to it, so;
• It builds to the default public folder
• In that folder, is an index.html file
• @ -Azure, please copy that folder, and deploy it.

I haven't been able to find a working combination of app_location, output_location and the other options.

Interestingly, searching for AzureStaticWebApp@0 doesn't yield much useful output, but at least I saw #5, which you can close this as a duplicate of.

Now, my observation after exceeding my daily reading time on this, and trying out the various combinations; is that this thing does not work.

Here's some outputs below:

Note how the second screenshot tells me about Github ...

(here's me changing stuff cos I don't know what I'm doing anymore)

Proposed Solution

May someone from Microsoft pleasy kindly take a bit of time, to do this (or whatever alternative that can work):

• Deploy a hugo website, and try out the pipeline thing.
• Update the documentation at https://docs.microsoft.com/en-us/azure/static-web-apps/publish-devops, because it does not work. This article was written < 2 weeks ago btw. I started here, and tweaked values until I lost my mind.
• Consider adding some notes about Pipelines + SWA (if the product is intended to be used as such), so that customers' expectations can be better met. I would have gone with a Blob Store static web thingy, or even built the site on a VM, Docker; etc. Plenty of options, but this seemed like the most convenient option. #5 shows some frustration from other customers.
• Consider extending Oryx's functionality to rather detect these config things. If I'm building a Jekyll website, and it does magic to detect that (and build using an old version :thumbs_down:), maybe it should extend the magic to also figuring out where my folders are.
• Consider adding the option (or documenting it) for one to just upload a site (and not build) on Azure Pipelines. I deliberately tried searching for the documentation, but could not find anything. I could otherwise have used my preferred Hugo version, and just uploaded.

For anyone unable to reproduce this, consider the below:

My reading of it says that my yaml config should be like:

  - task: AzureStaticWebApp@0
    inputs:
      app_location: "/" # app is in the root of the repo
      output_location: "public" # outputs (should) get built to the public folder
    env:
      azure_static_web_apps_api_token: $(deployment_token)

But I still get the below, and what's this ss-oryx/app thing? Is it relevant to my error?

[anthonychu]

Thanks for the feedback. I think there are some docs improvements we can make to avoid this confusion in the future. /cc @craigshoemaker

If you are building the app in a prior step, set the app_location to the build output folder (the files you want to deploy) and leave the output_location empty. Please give that a try and let us know if it works.

Can you tell us more about your Hugo site (version, etc)? The action should be able to build most Hugo sites automatically, I'd like to investigate why it's not able to build it for you.

[nevi-me]

Thanks @anthonychu for replying

I'm using version 0.82.0, but it doesn't seem that it's a Hugo version issue. I can confirm that even using an old version like 0.6x.x or 0.7x.x (which Oryx uses) does build the site.

Following your suggestion of building with my script and version of Hugo, and pointing the app_location = "public" or "/public", I now get a different error:

  - task: AzureStaticWebApp@0
    inputs:
      app_location: "/public" 
      # output_location: public
    env:
      azure_static_web_apps_api_token: $(deployment_token)

Given that it's now not able to detect a language, my diagnosis leads me back to the "magic" bit.

• The script tries to find a supported Oryx static site to build with, but fails if it doesn't find it (behaviour from your suggestion)
• Once it's found it to be Hugo, it builds the site correctly, but fails to find an index.html file even when it's there. (what's been happening)

Potential Solution

What is the GHA's equivalent of the below uncommented line? I think knowing that would have saved me a few hours, as people having the same issue as me on GHA have used this successfully.

# jobs:
  # build_and_deploy_job:
    # if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    # runs-on: ubuntu-latest
    # name: Build and Deploy Job
    # steps:
      # - uses: actions/checkout@v2
        # with:
         #  submodules: true
      # - name: Build And Deploy
        # id: builddeploy
        # uses: Azure/static-web-apps-deploy@v0.0.1-preview
        # with:
          # azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          # repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
          action: "upload"

I hope this helps

[nevi-me]

Using both action: "upload" or command: "upload" doesn't work. So if one of those would be the answer to my above question, then it doesn't work.

Here's the full azure-pipelines.yamlfile

# Starter pipeline
# Start with a minimal pipeline that you can customize to build and deploy your code.
# Add steps that build, run tests, deploy, and more:
# https://aka.ms/yaml

trigger:
  - main

pool:
  vmImage: ubuntu-latest

variables:
  hugo.version: '0.82.0'

steps:
  - script: |
     wget -c https://github.com/gohugoio/hugo/releases/download/v$(hugo.version)/hugo_$(hugo.version)_Linux-64bit.deb   
    displayName: "Download Hugo"

  - script: 'sudo dpkg -i hugo_$(hugo.version)_Linux-64bit.deb'
    displayName: "Install Hugo"

  - script: |
     cd $ touch-ways-of-working
     hugo --log -v
    displayName: 'Generate Site'

  - script: ls
    displayName: "List files"

  - task: AzureStaticWebApp@0
    inputs:
      action: upload
      # app_location: "/public" 
      output_location: public
    env:
      azure_static_web_apps_api_token: $(deployment_token)

[anthonychu]

What does cd $ touch-ways-of-working do? Is your Hugo app nested inside of a folder named touch-ways-of-working?

You don't need to set action: upload. If your app is inside a folder, below should be the Azure Static Web Apps task definition:

  - task: AzureStaticWebApp@0
    inputs:
      app_location: "touch-ways-of-working/public" 
    env:
      azure_static_web_apps_api_token: $(deployment_token)

[nevi-me]

@anthonychu that's some cruft on the scripts I suppose, but not relevant. Looking closer at it, I don't think it does anything (copy-pasta).

Trying to add the folder prefix returns this:

Here's the folder structure, and the pipelines yml is in the same folder:

[anthonychu]

Can you change the ls command to ls public to list out what's in the public folder? It looks like we can't find an index.html in that folder that's currently required to deploy the app.

Based on what you shared, assuming the public folder contains an index.html, this should be the task input:

  - task: AzureStaticWebApp@0
    inputs:
      app_location: "/public" 
    env:
      azure_static_web_apps_api_token: $(deployment_token)

[nevi-me]

We tried that at https://github.com/Azure/static-web-apps/issues/351#issuecomment-814278153, but Oryx doesn't detect a framework, and bails with an error (my comment about the magic).

Have you tried building a default Hugo site, and gotten it to work?

I did confirm that there's a public.html, which is what's also really odd for me.

I'm spinning up a VM and doing this the boring way tomorrow, maybe we can leave this issue open for a few weeks, and see if other Azure Pipelines users come across same issues as me?

Please feel free to change the title if you need to.

Thanks

[anthonychu]

It needs an index.html, not public.html. Can you please confirm you have an index.html in the public folder?

As the text in the following section says, it can’t detect a framework so it’s trying to deploy the site assuming it’s already built (which is true). However it can’t find an index.html, which is something we currently require.

[nevi-me]

Hi @anthonychu, I apologise for the confusion. public.html was a typo, I meant to say index.html.

[anthonychu]

Thanks for confirming. I think the problem is that the theme is missing. If you changed your list files step to run the command ls public, you should see that it's missing index.html. The index.html and other assets come from the theme.

@nevi-me This is likely because your theme is included as a submodule in your repo. To get Azure Pipelines to download submodules, add the checkout task. Take a look at this example that I tested to work with a Hugo app that has a submodule:

trigger:
- main

pool:
  vmImage: ubuntu-latest

steps:
- checkout: self
  submodules: true

- task: AzureStaticWebApp@0
  inputs:
    app_location: /
    output_location: public
  env:
    azure_static_web_apps_api_token: $(deployment_token)

I'll submit an update to the documentation that includes the task with submodules enabled by default.

[bhnat-cyclelabs]

@anthonychu Thanks for the samples. I wound up reading this issue trying to trouble an issue, except with Gatsby rather than Hugo where I frequently experienced, Oryx has timed out while building app, the current limit is 15 minutes. Failing build. After changing the pipeline from:

- task: AzureStaticWebApp@0
  inputs:
    app_location: 'docs/cycle-api'
    api_location: ''
    output_location: 'public'

to this, so that the app_location is the public folder (and removing the api_location and output_location entries):

- task: AzureStaticWebApp@0
  inputs:
    app_location: 'docs/cycle-api/public'

the build now passes in less than a minute.

[ArvindRSingh]

For the fourth time I'm restarting a blogging site with Hugo+ SWA and it stops deploying after a week or two. I'm fed up with this deployment process to say the least. Is it possible to manually deploy to Azure static web app? At least I'm assured it will be deployed.