Automatically update submodules when other repos push to `main`

[stevepiercy]

Description

Currently whenever there is a push to master for either repo plone/volto or plone/plone.restapi, we manually need to remember to update the submodule. See https://6.docs.plone.org/contributing/index.html#editing-external-package-documentation, Step 7.

cd ../..

# For plone.restapi
git add submodules/plone.restapi
git commit -m "Update submodules/plone.restapi tip"

# For volto
git add submodules/volto
git commit -m "Update submodules/volto tip"

git push

It would be great to handle this automatically in GitHub Actions.

[stevepiercy]

Apparently GitHub Actions does not support cross-repository workflows directly. However, here is an article that works around it using curl and secrets to trigger a cross-repository workflow.

https://utensils.io/articles/trigger-github-actions-from-another-repo

See also:

https://github.com/orgs/community/discussions/26323

First we need to create a workflow in this repository that will update the git submodule.

Then we need to work with the Volto team to add secrets to their repo which the Docs Team can provide, create a new workflow that runs only on pushes to master that calls the other workflow, and update .github/workflows/docs.yml to call the new workflow on success. Something like this, I think:

docs.yml success → call-remote-documentation.yml → update-submodule.yml

[stevepiercy]

@ericof how should secrets be generated and stored for the Plone organization? I can do the work, except for that bit.

[stevepiercy]

Reopening per #1346 (comment)