{"id":28142265,"url":"https://github.com/urob/zmk-actions","last_synced_at":"2026-01-07T23:17:48.389Z","repository":{"id":267482413,"uuid":"901394096","full_name":"urob/zmk-actions","owner":"urob","description":"Github workflows for maintaining ZMK modules","archived":false,"fork":false,"pushed_at":"2025-04-21T18:33:25.000Z","size":57,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-21T18:41:10.678Z","etag":null,"topics":["zmk","zmk-module"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urob.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-12-10T15:21:19.000Z","updated_at":"2025-04-21T18:32:28.000Z","dependencies_parsed_at":"2024-12-10T16:36:03.694Z","dependency_job_id":"71c0ed5a-a738-4e6b-9317-58430fb41df5","html_url":"https://github.com/urob/zmk-actions","commit_stats":null,"previous_names":["urob/zmk-modules-actions","urob/zmk-actions"],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urob%2Fzmk-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urob","download_url":"https://codeload.github.com/urob/zmk-actions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254209843,"owners_count":22032898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["zmk","zmk-module"],"created_at":"2025-05-14T19:20:07.159Z","updated_at":"2026-01-07T23:17:48.383Z","avatar_url":"https://github.com/urob.png","language":"Shell","readme":"# ZMK Actions\n\nThis repository contains several Github actions for ZMK users and developers. It also contains a nix\nshell that can be used as drop-in replacement for the ZMK Docker container, both locally and in\nGithub actions.\n\n## Actions\n\nActions for building ZMK firmware:\n\n- `build-user-config`: Drop-in replacement for the official docker-based build workflow.\n\nActions for ZMK module developers:\n\n- `upgrade-zmk`: Check for new ZMK releases and create matching module PRs\n   dependencies.\n- `run-tests`: Run automated module tests on pull requests.\n- `upgrade-module`: Create module versions to match ZMK version on merge.\n\nActions with special purposes and unlikely to be used directly:\n\n- `setup-sdk`: Set up nix shell with Zephyr SDK, `west` and other build dependencies.\n- `setup-zmk`: Create ZMK workspace with all required west modules.\n- `test`: Low-level action supporting `run-tests`.\n\n## Nix shell\n\nTodo: document `flake.nix` and add template for local usage.\n\n## Maintaining ZMK modules\n\nThe actions for developers are designed around automated module testing leveraging the same\n`native_posix`-based test environment used upstream. To make this work, the test environment is\ntied to a specific ZMK release.\n\nWhenever a new ZMK release is detected, the `upgrade-zmk` workflow creates a PR to bump the ZMK\nrelease used by the testing environment and then triggers the `run-tests` workflow using the new ZMK\nrelease. The outcomes of the tests are attached to the PR.\n\nIf all tests pass and the PR is merged, the `upgrade-module` workflow is triggered which adds a tag\nto the `head` of the module repository matching the ZMK release. It further adds or moves\ncorresponding `major` and `minor` version tags to the same commit.\n\n## Usage\n\n### 1. Add tests to your module\n\nBy default, the `run-tests` workflow looks for tests in the `tests` directory. All tests are\nexpected to follow the naming, design and syntax of the\n[ZMK test suite](https://zmk.dev/docs/development/local-toolchain/tests).\n\nIn addition, the `tests` directory should contain a `west.yml` file that defines the current test\nenvironment. If the only module dependency is ZMK, the `west.yml` file should look like this:\n\n```yaml\nmanifest:\n  remotes:\n    - name: zmkfirmware\n      url-base: https://github.com/zmkfirmware\n  projects:\n    - name: zmk\n      remote: zmkfirmware\n      revision: v0.1.0 # This will be maintained by the upgrade-zmk workflow\n      import: app/west.yml\n  self:\n    path: tests\n```\n\nFor an example, see the [`tests`](https://github.com/urob/zmk-leader-key/tree/main/tests) directory\nof the `urob/zmk-leader-key` module.\n\n### 2. Add workflows to your repository\n\nIn most cases, it should suffice to copy the contents of\n[`templates`](https://github.com/urob/zmk-actions/tree/main/templates) to your repository.\nThe following provides a more detailed explanation of each workflow recipe.\n\n#### 2a/ `upgrade-zmk`\n\nIt is recommended to configure `upgrade-zmk` as a cron job. The following will set up a daily check\nfor new ZMK releases:\n\n```yaml\nname: Check for new ZMK releases\non:\n  workflow_dispatch:\n  schedule:\n    - cron: \"0 22 * * *\" # Run daily at 22:00 UTC\njobs:\n  upgrade-zmk:\n    uses: urob/zmk-actions/.github/workflows/upgrade-zmk.yml@v8.0.1\n    permissions:\n      contents: write\n    secrets:\n      # \u003e\u003e\u003e Add a Personal Access Token with write access to pull requests here \u003c\u003c\u003c\n      token: ${{ secrets.ZMK_MODULES_ACTIONS }}\n```\n\nThe workflow supports the following optional input parameters:\n\n- `upstream` - The upstream ZMK repository to check for new releases. Defaults to `zmkfirmware/zmk`.\n- `west_path` - The path to the `west` manifest that defines the test environment. Defaults to\n  `tests/west.yml`.\n- `pr_branch` - The branch to create PRs in. Defaults to `upgrade-zmk`.\n- `pr_label` - A label to add to PRs. Defaults to none.\n\n#### 2b/ `run-tests`\n\nAt a minimum, `run-tests` should be triggered on pull requests to the `tests` directory. The\nfollowing sets up additional triggers for other pull requests and pushes:\n\n```yaml\nname: Run tests\non:\n  workflow_dispatch:\n  push:\n    paths:\n      - \"dts/**\"\n      - \"include/**\"\n      - \"src/**\"\n      - \"tests/**\"\n  pull_request:\n    paths:\n      - \"dts/**\"\n      - \"include/**\"\n      - \"src/**\"\n      - \"tests/**\"\njobs:\n  test:\n    uses: urob/zmk-actions/.github/workflows/run-tests.yml@v8.0.1\n```\n\nThe workflow supports the following optional input parameters:\n\n- `tests_path` - The path to the tests directory. Defaults to `tests`.\n\n#### 2c/ `upgrade-module`\n\n`upgrade-module` should be triggered on pull request merges to your `main` branch. The action will\nonly create a new release if the pull request title starts with `Bump ZMK`. So this is safe to run\non all merges.\n\n```yaml\nname: Release module version\non:\n  pull_request:\n    types:\n      - closed\n    branches:\n      - main\njobs:\n  release:\n    uses: urob/zmk-actions/.github/workflows/upgrade-module.yml@v8.0.1\n    permissions:\n      contents: write\n```\n\nThe workflow supports the following optional input parameters:\n\n- `release_branch` - The branch to create the release from. Defaults to `main`.\n\n### 3. Create a Personal Access Token\n\nThe `upgrade-zmk` workflow requires a Personal Access Token with write access to pull requests.[^1]\nThe following steps outline how to create the token:\n\n1. Go to your GitHub account settings.\n2. Create a new Personal Access token under Developer settings. (The name doesn't matter.)\n3. Configure the token to have the following repository permissions:\n   - Read access to metadata\n   - Write access to pull requests\n4. Copy the token and store it in a secure location.\n5. Go to the repository where you want to use the token.\n6. Go to 'Action secrets and variables' in the repository settings.\n7. Add a new repository secret with the same name as passed to `upgrade-zmk` in step 2a/ above.\n8. Set the secret value to the token you created in steps 1-4.\n\n[^1]:\n    This is so that the `upgrade-zmk` workflow can trigger the `run-tests` workflow. See\n    [here](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow)\n    for a full explanation.\n","funding_links":[],"categories":["Tools and Software"],"sub_categories":["CLI and Utilities"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furob%2Fzmk-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furob%2Fzmk-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furob%2Fzmk-actions/lists"}