New: Add GitHub Actions workflow to deploy v5 vanilla course to GitHub Pages (fix #3479)

[swashbuck]

Fix #3479

New

• Adds GitHub Actions workflow step to deploy v5 vanilla course to GitHub Pages: https://adaptlearning.github.io/v5demo/
• Workflow will run when a new release is published or every Tuesday at 7am UTC.

Update

• Update Node version environment to lts/* in test.yml

❓Questions

1. Should we update all node versions in the workflow files (ex. test.yml) to use the same version? If so, should we use lts/* or 18?
2. How do we "advertise" the new site? Add to the adapt_framework README.md, add to the wiki, etc?
   a. Noting that https://github.com/adaptlearning doesn't actually have a README.md doc. First time visitors may not realize that they need to visit the adapt_framework repo to get an overview. Separate issue to consider...
3. Would it be useful to run this workflow on a schedule so that the vanilla course always has the most up to date plugins? For instance, set this up to run once a week and refresh the site.

Technical explanations

How It Works

How It Works

1. releases.yml runs on push to master → semantic-release creates GitHub release + tag
2. GitHub release published → triggers build-and-deploy.yml. Note that the schedule also triggers this workflow.
3. Workflow runs npm ci → grunt build → deploys to master branch of adaptlearning/adaptlearning.github.io repo in the v5demo directory.
4. No cleanup needed (workflow runs in isolated environment)

Deployment Options Considered

Deployment Options Considered

peaceiris/actions-gh-pages@v4 (chosen):

• Community action with 11k+ stars, well-maintained since 2019
• Single-step deployment process
• Works with traditional gh-pages branch approach
• Supports external repository deployment
• Perfect for custom build tools like Grunt
• Simpler for release-triggered workflows

actions/deploy-pages (official GitHub alternative):

• Official GitHub action (launched ~2022)
• Two-step process: upload artifact → deploy
• Requires "Deploy from GitHub Actions" source setting (not branch-based)
• GitHub's stated direction for Pages
• Better for static site generators or complex CI/CD
• More modular but adds complexity for simple use cases

Key Differences

Deployment Method:

• peaceiris: Pushes content directly to a branch (typically gh-pages)
• actions/deploy-pages: Uses artifacts uploaded via actions/upload-pages-artifact

Official Status:

• peaceiris documentation acknowledges: "See also the GitHub official GitHub Pages Action first"
• GitHub announced in August 2022: "GitHub Pages now uses Actions by default"

Why We Chose peaceiris/actions-gh-pages@v4

For our specific use case (release-triggered Adapt course deployments with Grunt builds):

1. Simplicity - Single-step deployment vs two-step artifact approach
2. Branch-based - Works with traditional gh-pages branch setup
3. Proven - Widely used, well-documented, stable
4. No workflow changes needed - Works seamlessly with our release workflow

Both actions are valid and actively maintained. We chose peaceiris for simplicity, not because it's superior to the official action.

[swashbuck]

Ready for review.

[cahirodoherty-learningpool]

1. Should we update all node versions in the workflow files (ex. test.yml) to use the same version? If so, should we use lts/* or 18?
2. How do we "advertise" the new site? Add to the adapt_framework README.md, add to the wiki, etc?
   a. Noting that https://github.com/adaptlearning doesn't actually have a README.md doc. First time visitors may not realize that they need to visit the adapt_framework repo to get an overview. Separate issue to consider...
3. Would it be useful to run this workflow on a schedule so that the vanilla course always has the most up to date plugins? For instance, set this up to run once a week and refresh the site.

1. I would be in favour of using lts/*. Any updates to other scripts could be performed as a separate "Chore:" PR
2. Adding to the wiki definitely makes sense to me. I guess there's no harm in adding a reference to the FW Readme also
3. I would support running on a schedule. The testing action already runs on a daily schedule for this reason, but as you mentioned, a weekly run would suffice for this if its also running on publish/release/version-tag anyway

[oliverfoster]

Deploy to the external repository, please. We should definitely not add a build folder to this repo.

https://github.com/peaceiris/actions-gh-pages?tab=readme-ov-file#%EF%B8%8F-deploy-to-external-repository-external_repository

This repo is the expected destination: https://github.com/adaptlearning/adaptlearning.github.io
In folder v5demo.
Which looks like this on gh pages: https://adaptlearning.github.io/v5demo/

The token ${{ secrets.RELEASES_TOKEN}} or ${{ secrets.ADDTOPROJECT_TOKEN}} may work https://github.com/adaptlearning/adapt_framework/settings/secrets/actions.

[swashbuck]

Added the workflow_dispatch event so that we can run manually 8db2f2a