Add GitHub Actions workflow template & documentation

.github.example/workflows/build.yml

@@ -0,0 +1,63 @@
+name: Build
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    # This is a *private* build container.
+    # See docs/github_actions.md for more information.
+    container: ghcr.io/my/game-build:main
+
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add game versions here
+        version: [GAMEID]
+
+    steps:
+    # Checkout the repository (shallow clone)
+    - name: Checkout
+      uses: actions/checkout@v3
+      with:
+        fetch-depth: 0
+        submodules: recursive
+
+    # Set Git config
+    - name: Git config
+      run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
+
+    # Copy the original files to the workspace
+    - name: Prepare
+      run: cp -R /orig .
+
+    # Build the project
+    - name: Build
+      run: |
+        python configure.py --map --version ${{ matrix.version }} \
+            --binutils /binutils --compilers /compilers
+        ninja all_source build/${{ matrix.version }}/progress.json
+
+    # Upload progress if we're on the main branch
+    - name: Upload progress
+      # If you're using a different branch, change this to match
+      if: github.ref == 'refs/heads/main'
+      continue-on-error: true
+      env:
+        # Replace with your project slug
+        PROGRESS_SLUG: prime
+        # Set the API key in your repository secrets
+        PROGRESS_API_KEY: ${{ secrets.PROGRESS_API_KEY }}
+      run: |
+        python tools/upload_progress.py -b https://progress.decomp.club/ \
+          -p $PROGRESS_SLUG -v ${{ matrix.version }} \
+          build/${{ matrix.version }}/progress.json
+
+    # Upload map files
+    - name: Upload map
+      uses: actions/upload-artifact@v3
+      with:
+        name: ${{ matrix.version }}_maps
+        path: build/${{ matrix.version }}/**/*.MAP

README.md

@@ -12,6 +12,7 @@ Documentation
 - [Getting Started](docs/getting_started.md)
 - [`symbols.txt`](docs/symbols.md)
 - [`splits.txt`](docs/splits.md)
+- [GitHub Actions](docs/github_actions.md) (new!)
 
 General:
 
@@ -54,7 +55,7 @@ Features
 - No manual assembly: decomp-toolkit handles splitting the DOL into relocatable objects based on the configuration. No game assets are committed to the repository.
 - Progress calculation and upload script for [frogress](https://github.com/decompals/frogress).
 - Integration with [objdiff](https://github.com/encounter/objdiff) for a diffing workflow.
-- (TODO) CI workflow template for GitHub Actions.
+- CI workflow template for GitHub Actions.
 
 Project structure
 -----------------

docs/dependencies.md

@@ -5,7 +5,7 @@ Windows
 --------
 
 On Windows, it's **highly recommended** to use native tooling. WSL or msys2 are **not** required.  
-When running under WSL, [objdiff](#diffing) is unable to get filesystem notifications for automatic rebuilds.
+When running under WSL, [objdiff](https://github.com/encounter/objdiff) is unable to get filesystem notifications for automatic rebuilds.
 
 - Install [Python](https://www.python.org/downloads/) and add it to `%PATH%`.
   - Also available from the [Windows Store](https://apps.microsoft.com/store/detail/python-311/9NRWMJP3717K).

docs/getting_started.md

@@ -2,27 +2,27 @@
 
 See [Dependencies](dependencies.md) first.
 
-Clone this template repository.
+1. [Create a new repository from this template](https://github.com/new?template_name=dtk-template&template_owner=encounter), then clone it.
 
-Rename `orig/GAMEID` to the game's ID. (For example, `GLZE01` for _The Legend of Zelda: The Wind Waker_.)
+2. Rename `orig/GAMEID` to the game's ID. (For example, `GLZE01` for _The Legend of Zelda: The Wind Waker_.)
 
-Extract your game to `orig/[GAMEID]`. In Dolphin, use "Extract Entire Disc" for GameCube games, or use "Data Partition" -> "Extract Entire Partition" for Wii games.
+3. Extract your game to `orig/[GAMEID]`. In Dolphin, use "Extract Entire Disc" for GameCube games, or use "Data Partition" -> "Extract Entire Partition" for Wii games.
 
-Rename `config/GAMEID` to the game's ID and modify `config/[GAMEID]/config.yml` appropriately, using [`config.example.yml`](/config/GAMEID/config.example.yml) as a reference. If the game doesn't use RELs, the `modules` list in `config.yml` can be removed.
+4. Rename `config/GAMEID` to the game's ID and modify `config/[GAMEID]/config.yml` appropriately, using [`config.example.yml`](/config/GAMEID/config.example.yml) as a reference. If the game doesn't use RELs, the `modules` list in `config.yml` can be removed.
 
-Generate a `config/[GAMEID]/build.sha1` file for verification. This file is a list of SHA-1 hashes for each build artifact. One possible way:
+5. Generate a `config/[GAMEID]/build.sha1` file for verification. This file is a list of SHA-1 hashes for each build artifact. One possible way:
 
-```sh
+    ```sh
-dtk shasum orig/[GAMEID]/sys/main.dol orig/[GAMEID]/files/*.rel > config/[GAMEID]/build.sha1
+    dtk shasum orig/[GAMEID]/sys/main.dol orig/[GAMEID]/files/*.rel -o config/[GAMEID]/build.sha1
-```
+    ```
 
-Then, modify the paths in `config/[GAMEID]/build.sha1` to point to the `build` directory instead of `orig`. The DOL will be built at `build/[GAMEID]/main.dol`, and modules will be built at `build/[GAMEID]/[module_name]/[module_name].rel`.
+6. Modify the paths in `config/[GAMEID]/build.sha1` to point to the `build` directory instead of `orig`. The DOL will be built at `build/[GAMEID]/main.dol`, and modules will be built at `build/[GAMEID]/[module_name]/[module_name].rel`.
 
-Update `VERSIONS` in [`configure.py`](/configure.py) with the game ID.
+7. Update `VERSIONS` in [`configure.py`](/configure.py) with the game ID.
 
-Run `python configure.py` to generate the initial `build.ninja`.
+8. Run `python configure.py` to generate the initial `build.ninja`.
 
-Run `ninja` to perform initial analysis.
+9. Run `ninja` to perform initial analysis.
 
 If all goes well, the initial `symbols.txt` and `splits.txt` should be automatically generated. Though it's likely it won't build yet. See [Post-analysis](#post-analysis) for next steps.
 

docs/github_actions.md

@@ -0,0 +1,52 @@
+# GitHub Actions
+
+This repository includes [.github.example/workflows/build.yml](/.github.example/workflows/build.yml) as an example CI workflow. To use it for your project, follow the setup instructions below.
+
+- [Build Repository](#build-repository)
+- [Progress](#progress)
+- [Workflow](#workflow)
+
+## Build Repository
+
+This repository will be used to build and store the CI build container.
+
+> [!CAUTION]
+> This repository should be **private** to avoid exposing the game's assets.
+
+1. [Create a **private** repository from `encounter/dtk-template-build`](https://github.com/new?template_name=dtk-template-build&template_owner=encounter). A common name is your project's repository name with `-build` appended. For example, `tww-build`.
+
+2. Once the repository is created, add your game's assets to the `orig/GAMEID` directory. (Replace `GAMEID` with your game's ID, matching the `orig` layout in your main repository.)  
+    **Only include game files necessary for the build**, such as `sys/main.dol` and any `.rel` or `.sel` files.
+
+3. Once the build container action completes, visit the package settings:  
+    ![GitHub repository packages](images/github_build_repo_packages.png)  
+    ![GitHub package settings](images/github_package_settings.png)
+
+4. Under "Manage Actions access", add your project's main repository with the "Read" role:  
+    ![GitHub package Actions access](images/github_package_settings_access.png)
+
+## Progress
+
+1. In the [GC/Wii Decompilation Discord](https://discord.gg/hKx3FJJgrV), visit `#frogress` and request an API key for your project.  
+    Please provide the following:
+    - Project name
+    - Repository URL
+    - Game ID(s)
+    - Whether the game has RELs
+
+2. On GitHub, visit your repo's `/settings/secrets/actions/new` and add a new secret with the name `PROGRESS_API_KEY`:  
+    ![GitHub Actions secrets](images/github_actions_secrets.png)
+
+## Workflow
+
+1. Rename `.github.example` to `.github`.
+
+2. In `build.yml`, update the `container:` to point to the new [build image](#build-repository).
+
+3. In `build.yml`, replace `GAMEID` with your game's ID. (Or list of IDs, for multi-version support.)
+
+4. In `build.yml`, update `PROGRESS_SLUG` to match the project name on [frogress](#progress).
+
+5. Commit and push the changes to your repository.
+
+If everything is set up correctly, the workflow will build all versions on every push or pull request, and upload progress on pushes the `main` branch.