Build OpenWrt Packages in the Cloud with GitHub, No More Local Environment Setup

For many OpenWrt enthusiasts and developers, compiling packages for different target architectures can be a repetitive and time-consuming task. Setting up different environments every time is very troublesome, so I developed and open-sourced OpenWrt Package Builder, an automated workflow based on GitHub Actions that aims to make compiling OpenWrt packages unprecedentedly simple and efficient.

You only need to upload your package source code to a GitHub repository, choose a preset workflow, and modify two configuration variables, and it will automatically compile .ipk files for multiple target platforms. Below is the project’s README.md

A simple, universal, and out-of-the-box GitHub Actions workflow for automatically compiling any OpenWrt package. This project provides two build modes: SDK mode (recommended) and source mode, to suit different needs.

You only need to put your package source code in the repository, choose a workflow file, and modify two variables, and it will automatically compile .ipk files for multiple target architectures.

✨ Features#

🚀 Easy to use: Just copy and paste the workflow file and modify two environment variables.
⚡️ Lightning-fast builds (SDK mode): Use the official pre-compiled SDK to cut build time from 30+ minutes to under 5 minutes.
💡 Flexible and powerful (source mode): Can compile any package, including kernel modules, and supports development branches such as master.
⚙️ Highly versatile: Can be used to compile any type of OpenWrt package, including LuCI applications, command-line tools, and kernel modules.
🎯 Multi-target builds: Defaults to common architectures such as x86_64, armv8, mips_mt7621, and can be easily customized.
📦 Automatic release: After a successful build, the .ipk files are automatically uploaded as build artifacts for easy download.
💬 Commit comments: (Optional) After all build jobs succeed, a comment is automatically posted on the corresponding commit with links to download the artifacts.

🤔 How to choose a build mode?#

This project provides two workflows. Choose one based on your needs.

Feature / Scenario	✅ SDK mode (recommended)	⚠️ Source mode
Build speed	Extremely fast (usually < 1 minute)	Slow (first build > 40 minutes, subsequent builds use cache)
Supported package types	Most LuCI apps and regular packages	All packages, especially kernel modules (`kmod-xxx`)
Supported OpenWrt versions	Only official releases (e.g. `v23.05.3`)	All versions, including the `master` development branch
Workflow file	`build-with-sdk.yml`	`build-from-source.yml`

In short: if you’re unsure, or you’re just compiling a LuCI app, prefer SDK mode.

🚀 How to use#

An example#

If anything is unclear, refer to this example.

Step 1: Choose and create the workflow file#

Based on the choice above, create the corresponding .github/workflows/ directory and YAML file in your repository root.

For SDK mode: create .github/workflows/build.yml
For source mode: create .github/workflows/build-nonSDK.yml

Step 2: Copy the workflow code#

Based on your choice in the previous step, copy the full code of the corresponding file in this repository.

➡️ The code of build-with-sdk.yml
➡️ The code of build-from-source.yml

Step 3: Modify the configuration#

Open the YAML file you created. You only need to modify two variables in the env section:

PACKAGE_NAME: Change its value to the directory name of your package. Very important — this name must exactly match the name of the folder holding your package in the repository.
OPENWRT_VERSION: Set which OpenWrt version you want to build against.
- When using SDK mode: it must be an official release tag, e.g. v23.05.3.
- When using source mode: it can be any tag or branch name, e.g. v23.05.3 or master.

Tip: Don’t forget to update the badge links at the top of the README.md, replacing Tokisaki-Galaxy/openwrt-package-builder-action with your own!

Step 4: Check the Makefile (important)#

Make sure all dependencies are correctly defined in the Makefile file in your package directory. This workflow relies on make defconfig to automatically resolve and select these dependencies.

For example:

1
define Package/my-cool-package
2
  # ...
3
  DEPENDS:=+libcurl +libjson-c +some-other-package
4
endef

Step 5: Commit and run#

Commit and push your code along with the YAML file under .github/workflows/ to GitHub. GitHub Actions will start running automatically.

You can watch the build progress in the Actions tab of your repository. After the build completes, you can find and download the Artifacts on the corresponding run page.

🔧 Customization#

Modifying build targets#

If you need to compile for other architectures, you can modify the jobs.build.strategy.matrix.target section in the workflow file. Just add or modify entries following the existing format.