docs/en-us/develop/ci-tutorial.md
MAA leverages GitHub Actions to complete a large amount of automation work, including website building, automatic resource updates, final file building and release processes, etc. Over time, these CI workflows have gradually become nested, with some even pointing to other repositories. This document aims to provide a brief introduction for those who want to improve MAA's CI system.
Before reading this document, it's best to have a basic understanding of MAA's project structure and components.
::: tip You can quickly navigate to the section you want to see by searching for CI file names within this page :::
Workflow files are all stored under .github/workflows, and each file can be categorized into the following functional parts:
Additionally, we use pre-commit.ci to implement automatic code formatting and image resource optimization, which runs automatically after creating PRs and generally requires no special attention.
smoke-testing.yml
This workflow is mainly responsible for basic testing of MaaCore, including resource file loading, simple task execution tests, etc.
Since test cases haven't been updated for a long time, this workflow is now basically used to ensure resource files don't contain errors and that MaaCore code doesn't have fatal errors (the kind that affects building).
ci.yml
This workflow is responsible for full code building work, including all MAA components. The build artifacts are runnable MAA instances.
In addition to the necessary MaaCore, Windows build artifacts include MaaWpfGui, macOS build artifacts include MaaMacGui, Linux build artifacts include maa-cli, and the Android version of MaaCore is also built.
This workflow runs automatically on new commits to dev-v2 that touch source code or build scripts, as well as on PRs. When triggered by a version tag (created by pr-auto-tag.yml after the release PR is merged), the build artifacts from this run will be used directly for release and a Release will be created.
Version release is the necessary operation to publish updates to users, consisting of the following workflows:
release-nightly-ota.yml Release nightly buildsrelease-ota.yml Release stable/beta versions
release-preparation.yml Generate changelog and prepare release for stable/beta versionspr-auto-tag.yml Generate tags for stable/beta versions::: tip The "ota" in the above file names stands for Over-the-Air, which is what we commonly call "incremental update packages". Therefore, MAA's release process actually includes building OTA packages for past versions. :::
release-nightly-ota.yml
This workflow runs automatically at 22:00 UTC daily to ensure nightly build release frequency. Of course, you can also manually release when making changes that need verification.
Note that nightly builds are only released for Windows users; macOS and Linux users cannot receive nightly updates.
The release process for these two channels is relatively more complex. We'll explain the role of each workflow by simulating a release process:
dev-v2 to master-v2 branch, and the PR name must be Release v******release-preparation.yml generates a changelog from the most recent stable/beta version to the current version (as a new PR)pr-auto-tag.yml to create tags and sync branchesrelease-ota.yml, which builds OTA packages and uploads attachments after tagging master-v2This section of workflows is mainly responsible for MAA's resource updates and optimization, with the following specific workflows:
res-update-game.yml Executes periodically to pull game resources from specified repositoriessync-resource.yml Syncs resources to the MaaResource repository for resource updatesoptimize-templates.yml Optimizes template image sizeswebsite-workflow.yml
This workflow is mainly responsible for building and publishing MAA's documentation site.
Please note that website publishing is tightly bound to releases. Regular modifications to web components only trigger builds to ensure no errors occur, and actual deployment to GitHub Pages only happens during releases.
issue-checker.yml
Uses regex matching to tag various Issues, categorizing and marking Issue content for easier viewing and management.
issue-checkbox-checker.yml
Uses regex matching to automatically close Issues that check "I have not read carefully". If "I have not read carefully" is not checked, all checkboxes are collapsed.
stale.yml
Checks Issues that have had no activity for more than 90 days (excluding Pull Requests, and exempting Issues labeled keep-open, MAA Team, or enhancement), marks them and sends notifications, then closes them after 7 more days if still inactive.
pr-checker.yml
This workflow checks whether commit messages in PRs conform to Conventional Commits and whether they contain merge commits. If any commit fails to meet the requirements, a comment is posted as a reminder and the check is made to fail.
MirrorChyan is a paid update mirror service, with the following related workflows:
release-package-distribution.yml Sync update packages to MirrorChyanmirrorchyan_release_note.yml Generate MirrorChyan Release Notesmarkdown-checker.yml
Responsible for checking all Markdown files in the repository for invalid links.
blame-ignore.yml
Automatically ignores commits with commit messages containing blame ignore to keep repository history clean.
cache-delete.yml
Cleans up related caches after PR merges to save cache usage.
update-submodules.yml
Periodically updates submodules such as MaaMacGui and maa-cli to their latest versions. This workflow runs automatically at 21:50 UTC daily (before the nightly release), ensuring submodules remain up to date.