Workflows

The repository contains several workflows used to automate some specific tasks either by event (push) or on a schedule. For example, we use a test workflow for unit testing, which runs whenever a pull request is opened or updated.

All workflow settings are written in .yml files, and are are stored in .github/workflows, which is a location used by Github to load and configure actions on the repository.

You must enable Actions in your repository settings if you wish workflows to run.

Enabling Actions

• Log in as a repository administrator.
• Navigate to Settings > Actions and tick Allow all actions.
• Navigate to Settings > Branches > Branch protection rules and select Add rule.
• Under Branch name pattern, enter dev or the name of your active branch.
• Under Protect matching branches, tick Require status checks to pass before merging.
• Under Status checks found for this repository tick Code and all checks beginning with Maps.
• Save changes.

Configuring the changelog bot

Due to branch protection preventing automatic pushing of commits to the dev branch, the workflows use a bot account with administrator privileges to generate and push the changelog commits in make_changelogs.yml and changelog_generation.yml. This requires some configuration to get working.

• Create a bot user and email.
• Add the bot to the repository as an administrator under Settings > Manage access. Admin is necessary for the bot to function.
• Log into the bot account and accept the invitation.
• Generate a personal access token with full repo permissions for the bot user. Keep this handy as you can't view it again after the initial creation, losing it means you need to make a new one.
• Navigate to Settings > Secrets on the repository.
• Create BOT_NAME containing the bot account name.
• Create BOT_EMAIL containing the bot email address.
• Create BOT_TOKEN containing the personal access token.
• Optionally, create WEBHOOK_URL containing a Discord webhook endpoint to report CI failure when the test workflow runs.

Current workflows

Here is list of the workflows in the repository at time of writing, along with a description of their function and some instructions on how to configure them. If you add a new workflow, please update this list.

1. test.yml

Description:

This workflow runs on pull requests (opened or updated) and conducts CI and unit testing for each configure map. If enabled, this workflow must pass for a PR to be mergable without admin overrides.

Installation steps:

Other than the webhook secret setup detailed under Configuring the changelog bot, this one doesn't require specific setup and should work as soon as workflows are enabled on the repository.

2. make_changelogs.yml

Description:

This workflow creates a new .yml file in html/changelogs based on the body of a merged pull request. Refer to the pull request template for specific syntax.

Installation steps:

Refer to Configuring the changelog bot for necessary setup for this webhook to run.

3. changelog_generation.yml

Description:

This workflow runs on a schedule, currently set to once a day, and will compile all .yml files in html/changelogs into a single HTML document that is shown to players when joining the server.

Installation steps:

Refer to Configuring the changelog bot for necessary setup for this webhook to run.