Multi-spec repositories, Echidna tokens and build overrides

[tidoust]

I haven't tried it yet but I'm surprised that multi-spec repositories support actually works as documented. Aren't Echidna tokens per spec? Cc @deniak

Also, GH_PAGES_BUILD_OVERRIDE and W3C_BUILD_OVERRIDE are typically settings that one would want to set on individual specs, and the use of a source/destination matrix for multi-spec repositories does not seem to allow that. For instance, a repo could contain a spec that needs to be published as WD and a spec that needs to be published as CRD.

All of the above can be solved by using the workaround that separates worfklows. I'm wondering whether that could be the right way to do it in practice (a tad verbose perhaps), and not only a workaround...

[sidvishnoi]

I think my attempt to keep the example short might have made it a bit misleading. Following is a more complete example:

name: CI
on:
  pull_request: {}
  push:
    branches: [main]
jobs:
  main:
    name: Build, Validate and Deploy
    runs-on: ubuntu-20.04
    strategy:
      matrix:
        include:
          - source: spec.html
            destination: index.html
            echidna-token: ${{ secrets.ECHIDNA_TOKEN }}
          - source: spec-1
            destination: the-spec
            echidna-token: ${{ secrets.ECHIDNA_TOKEN_SPEC_1 }}
          - source: spec-2
            # destination defaults to spec-2/index.html
            echidna-token: ${{ secrets.ECHIDNA_TOKEN_SPEC_2 }}
    steps:
      - uses: actions/checkout@v2
      - uses: w3c/spec-prod@v2
        with:
          SOURCE: ${{ matrix.source }}
          DESTINATION: ${{ matrix.destination }}
          GH_PAGES_BRANCH: gh-pages
          W3C_ECHIDNA_TOKEN: ${{ matrix.echidna-token }}
          W3C_WG_DECISION_URL: "https://lists.w3.org/Archives/Public/xyz.html"

W3C_WG_DECISION_URL, GH_PAGES_BUILD_OVERRIDE, W3C_BUILD_OVERRIDE etc. can also be specified via the strategy matrix, if needed.

IIRC, GitHub Actions also support an "or" operation, so we can have defaults like:
W3C_ECHIDNA_TOKEN: ${{ matrix.echidna-token || secrets.DEFAULT_ECHIDNA_TOKEN }}

using the workaround that separates workflows.

I think that would depend on how many specs there are, and how many custom options the workflow needs. Both are right ways to do things, and are supported by the action.

Primary concern with separate workflows is maintenance (like updating version in uses: w3c/spec-prod@v2 across multiple files, instead of one place; repetition and manual on.<push|pull_request>.paths). Might be worth trying it in practice to check what works better for multi-spec repos.

[tidoust]

Ah, got it, I wasn't familiar with this strategy feature, and thought it was handled by the action code itself, not by the GitHub workflow. All is good then!

I don't really know which of these approaches will work better. I wouldn't be surprised if different groups choose different approaches ;)

[tidoust]

I'm reopening this issue because I'm running into problems with secrets at the matrix level now that I've tried to apply the above to the WebCodecs repository:
https://github.com/w3c/webcodecs/blob/main/.github/workflows/pr-push.yml#L26

The action fails to run with: "The workflow is not valid. .github/workflows/pr-push.yml (Line: 26, Col: 28): Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.ECHIDNA_TOKEN_WEBCODECS".

The secrets do exist and the error seems to be with the secrets context itself. Could it be unavailable at that level? Or am I missing something obvious?

[tidoust]

The secrets context is indeed not available in matrix, see Secrets in matrix.

As suggested in that thread, a workaround that seems to work is to list the secret name at the matrix level and to dereference the name in the actual step with ${{ secrets[matrix.echidna_token] }}. It's a tad convoluted, but I confirm it works.

@sidvishnoi let me know if you see a better way to do that. It would probably be a good idea to document the pattern in the examples page otherwise :)

[sidvishnoi]

@tidoust Thanks for figuring this out. I think this is the best way, if it works.

I'll keep this issue open until I get time to document it.

[sidvishnoi]

Resolved in #77