diff --git a/.github/workflows/qmk_keymap.yml b/.github/workflows/qmk_keymap.yml new file mode 100644 index 0000000000..fb0ac4138a --- /dev/null +++ b/.github/workflows/qmk_keymap.yml @@ -0,0 +1,96 @@ +name: Build qmk_keymap repo + +on: + workflow_call: + inputs: + qmk_repo: + description: 'qmk_firmware repo to build against' + default: 'qmk/qmk_firmware' + required: false + type: string + qmk_ref: + description: 'qmk_firmware branch to build against' + default: 'master' + required: false + type: string + +permissions: + contents: write + +jobs: + prep: + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.set-matrix.outputs.matrix }} + + steps: + - name: Checkout userspace + uses: actions/checkout@v3 + + - name: Configure build targets + id: set-matrix + run: | + data="" + delim="" + for file in *.json; do + data="${data}${delim}{\"file\":\"$file\"}" + delim="," + done + echo "matrix={\"include\":[$data]}" >> $GITHUB_OUTPUT + + build: + needs: prep + runs-on: ubuntu-latest + container: qmkfm/qmk_cli + + strategy: + fail-fast: false + matrix: ${{ fromJSON(needs.prep.outputs.matrix) }} + + steps: + - name: Checkout QMK + uses: actions/checkout@v3 + with: + repository: ${{ inputs.qmk_repo }} + ref: ${{ inputs.qmk_ref }} + submodules: recursive + + - name: Checkout userspace + uses: actions/checkout@v3 + with: + path: users/${{ github.actor }} + + - name: Install missing dependencies + run: pip3 install -r requirements.txt + + - name: Build firmware + run: qmk compile -j=4 "users/${{ github.actor }}/${{ matrix.file }}" + + - name: Archive firmware + uses: actions/upload-artifact@v3 + continue-on-error: true + with: + name: ${{ matrix.file }}_${{ github.actor }} + path: | + *.hex + *.bin + *.uf2 + + publish: + needs: build + runs-on: ubuntu-latest + + steps: + - uses: actions/download-artifact@v3 + + - uses: marvinpinto/action-automatic-releases@latest + if: always() + with: + repo_token: "${{ github.token }}" + automatic_release_tag: "latest" + title: "Latest Firmware" + prerelease: false + files: | + **/*.hex + **/*.bin + **/*.uf2 diff --git a/docs/newbs_building_firmware_workflow.md b/docs/newbs_building_firmware_workflow.md index 99b32f0b71..70547f3fc9 100644 --- a/docs/newbs_building_firmware_workflow.md +++ b/docs/newbs_building_firmware_workflow.md @@ -56,26 +56,23 @@ If your GitHub account is not configured for [authenticated Git operations](http * [Personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) * [Connecting with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh) -### 3. Create a repository +## Create a repository -You will need a personal GitHub repository to host your QMK code. Follow [this guide](https://docs.github.com/en/get-started/quickstart/create-a-repo#create-a-repository) to create one named `qmk_keymap`. Do not proceed to commit any files just yet. +You will need a personal GitHub repository to host your QMK code. The template provided at is pre-configured for the workflow detailed here. Follow [this guide](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template#creating-a-repository-from-a-template) and create a repo based off the template named `qmk_keymap`. +### Clone repository + +Run the following commands in your computer to create a folder with a few template files (replacing `gh-username` with your GitHub user name): +``` +git clone https://github.com/gh-username/qmk_keymap +``` + +?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. + +?> For Windows user running MSYS, the above command will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. ## Initial Code Commit -### Create template files - -Run the following commands in your computer to create a folder with a few template files: -``` -mkdir -p ~/qmk_keymap/.github/workflows -touch ~/qmk_keymap/.github/workflows/build.yml -touch ~/qmk_keymap/config.h -echo "SRC += source.c" > ~/qmk_keymap/rules.mk -echo "#include QMK_KEYBOARD_H" > ~/qmk_keymap/source.c -``` - -?> For Windows user running MSYS, those commands will create the folder `qmk_keymap/` and its content in the `C:\Users\\qmk_keymap\` path location. - ### Add a JSON keymap Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file: @@ -85,55 +82,6 @@ Visit the [QMK Configurator](https://config.qmk.fm/#/) to create a keymap file: 3. Customise the key layout according to your preference. 4. Select download next to **KEYMAP.JSON** and save the JSON file into the `~/qmk_keymap/` folder. -### Add a GitHub Action workflow - -Open the file `~/qmk_keymap/.github/workflows/build.yml` with your favorite [text editor](newbs_learn_more_resources.md#text-editor-resources), paste the following workflow content, and save it: -```yml -name: Build QMK firmware -on: [push, workflow_dispatch] - -jobs: - build: - runs-on: ubuntu-latest - container: qmkfm/qmk_cli - strategy: - fail-fast: false - matrix: -# List of keymap json files to build - file: - - username.json -# End of json file list - - steps: - - - name: Checkout QMK - uses: actions/checkout@v3 - with: - repository: qmk/qmk_firmware - submodules: recursive - - - name: Checkout userspace - uses: actions/checkout@v3 - with: - path: users/${{ github.actor }} - - - name: Build firmware - run: qmk compile "users/${{ github.actor }}/${{ matrix.file }}" - - - name: Archive firmware - uses: actions/upload-artifact@v3 - continue-on-error: true - with: - name: ${{ matrix.file }}_${{ github.actor }} - path: | - *.hex - *.bin - *.uf2 -``` -Replace `username.json` with the JSON file name that was downloaded from [QMK Configurator](https://config.qmk.fm/#/) in the previous step. - -!> Do note that the `build.yml` file requires ***proper indentation*** for every line. Incorrect spacing will trigger workflow syntax errors. - ### Commit files to GitHub If you have completed all steps correctly, the folder `qmk_keymap/` will contain the following files: @@ -147,17 +95,13 @@ If you have completed all steps correctly, the folder `qmk_keymap/` will contain |-- username.json ``` -To commit and push them into GitHub, run the following commands (replacing `gh-username` with your GitHub user name): +To commit and push them into GitHub, run the following commands: ``` cd ~/qmk_keymap -git init git add -A git commit -m "Initial QMK keymap commit" -git branch -M main -git remote add origin https://github.com/gh-username/qmk_keymap.git -git push -u origin main +git push ``` -?> Use your GitHub personal access token at the password prompt. If you have setup SSH access, replace `https://github.com/gh-username/qmk_keymap.git` with `git@github.com:gh-username/qmk_keymap.git` in the remote origin command above. ### Review workflow output @@ -165,8 +109,11 @@ Files committed to GitHub in the previous step will automatically trigger the wo 1. Visit your "**qmk_keymap**" repository page on [GitHub](https://github.com/). 2. Select **Actions** tab to display the "**Build QMK Firmware**" workflow. 3. Select that workflow to display its run from the last commit. -4. Successfully compiled firmware will be under the "**Artifacts**" section. -5. If there are build errors, review the job log for details. +4. If there are build errors, review the job log for details. + +### Flashing + +Successfully compiled firmware will be under the "**Releases**" section, . Download and flash the firmware file into your keyboard using [QMK Toolbox](https://docs.qmk.fm/#/newbs_flashing?id=flashing-your-keyboard-with-qmk-toolbox). @@ -177,12 +124,6 @@ This setup and workflow relies on the QMK [Userspace](https://docs.qmk.fm/#/feat * Keymap layout files must be retained in JSON format and cannot be converted to `keymap.c`. * User callback and functions (e.g. `process_record_user()`) can be placed in the `source.c` file. -* Multiple keymap JSON files can be built in the same workflow. List them under `matrix.file:`, e.g.: -```yml - file: - - planck.json - - crkbd.json -``` * Code changes will require Git commit into GitHub to trigger the build workflow.