# Alpine's aports repository: the APKBUILD tree that builds every Alpine package > The aports repository holds the APKBUILD build scripts for every Alpine Linux package, split into main, community, and testing. This review covers its structure, workflow, and the trade-offs of relying on a GitLab-hosted, mirror-only source. **alpinelinux/aports** — [MIRROR] Alpine packages build scripts - Repository: https://github.com/alpinelinux/aports - Website: https://gitlab.alpinelinux.org/alpine/aports - Stars: 732 · Forks: 714 - Language: Shell - License: not declared - Published: 2026-08-27 · Updated: 2026-08-27 · Language: en - Canonical page: https://hysenlabs.com/projects/alpinelinux-aports ## What aports actually is The alpinelinux/aports repository is the source of truth for Alpine Linux package definitions. It contains an APKBUILD file for every package, plus the patches and scripts needed to build them. It is not a package manager and it does not ship binaries. It is a collection of build recipes. The README calls it a mirror, and the repository is hosted on GitHub as a copy of the canonical GitLab instance at gitlab.alpinelinux.org. If you work with Alpine, this is where you look to understand how a package is built or to propose a change. ## The three-tier repository structure The tree is divided into three directories: main, community, and testing. Each has its own policy. main holds packages expected in a basic system, with a dedicated maintainer, proper documentation, and enabled test suites. community is for packages that do not belong in main but have finished testing. testing is a staging area: packages there only need to build correctly, with no release cycle commitment. The README states that testing packages are not included in official releases and only ship in the edge branch. New packages follow the workflow testing to main or testing to community. This tiering is a practical way to separate experimental work from stable deliverables, but it also means that a package in testing can disappear if it is not promoted within a defined period. The README gives a concrete timeline: if a package is not moved within six months, the maintainer is notified and it is removed after nine months. That is a hard constraint that anyone relying on a testing package must respect. ## How APKBUILD files work An APKBUILD is a shell script that defines how to fetch, build, and package a piece of software. The repository does not include a full APKBUILD example in the README, but the coding style guide referenced as CODINGSTYLE.md covers the conventions. Based on the repository layout, each package directory contains an APKBUILD and possibly patches. The build system reads these files to produce .apk packages. The scripts are written in shell, which matches the primary language listed for the repository. This design keeps the build logic transparent and auditable, but it also means that the quality depends on the skill of each package maintainer. There is no central build engine here, only the definitions. ## Getting the tree and using the git hooks To work with aports locally, you clone the repository. The README gives one concrete command for setting up git hooks: git config --local core.hooksPath .githooks. This makes the hooks in the .githooks directory active for that clone. The hooks are meant to help with commit style and other checks. The contributor guide is linked, and the README mentions two contribution paths: a merge request on GitLab or a git patch sent to the aports mailing list. However, the README adds a warning that the mailing list is presently not functional. That is a significant limitation. If you want to contribute, the practical route is the GitLab merge request, not email. The GitHub mirror is described as a mirror, so you should not open pull requests there if you expect them to be processed. ## The testing repository is a trap for the unwary The testing repository is the most volatile part of aports. Packages there do not follow the release cycle and are not in official releases. They only need to build correctly. This is a low bar, so a testing package may work in one Alpine version and break in the next. The README explicitly says that testing packages are only shipped in the edge branch. If you are building a production system on edge and depend on a testing package, you must be prepared for removal. The six-month notification and nine-month removal policy is a real risk. For a long-term deployment, you should move the package to community or main yourself, or vendor the APKBUILD into your own tree. This is not a failure of aports, but it is a design choice that prioritizes experimentation over stability. ## Alternatives: local build definitions vs. package managers If aports is not suitable, the main alternative is to write your own build scripts or use a higher-level build system. Alpine uses abuild, which is a separate tool, but aports is the collection of recipes. A direct alternative is to maintain a private fork of aports or a separate overlay repository with your own APKBUILDs. This gives you control over versions and patches, but you lose the community maintenance and testing. Another approach is to use a binary package manager like apk with the official Alpine repositories, which avoids building from source altogether. The difference is that aports gives you the source-level definitions, while apk gives you prebuilt packages. For most users, apk is enough. For maintainers, aports is the only way to contribute back. ## Maintenance cost and licensing The repository is actively maintained, but the GitHub mirror may not be the primary source. The README says it is a mirror, and the homepage points to GitLab. That means you should track the GitLab instance for the latest changes. The license is listed as unknown in the metadata, but the README does not state a license. This is a gap. If you plan to reuse APKBUILD files in your own project, you need to check the individual files for license headers. The repository is not archived, and the default branch is master, so it is under active development. The maintenance cost for a contributor is moderate: you need to follow the coding style and commit style guidelines, and you need to respond to the six-month testing policy. For a user, the cost is low, because you just clone and read. ## Conclusion Adopt aports if you maintain or package software for Alpine Linux and need the canonical build definitions. Avoid it if you expect a ready-made binary package manager or if you need a stable, release-tagged source. Before relying on it, verify the current state of the mailing list and confirm that the GitLab instance is accessible from your CI, since the GitHub mirror may lag and the mailing list is not functional. ## FAQ ### What is the Alpine Linux aports repository? It holds the APKBUILD file for every Alpine Linux package, together with the patches and scripts each one needs, plus extra files for building and testing them through GitLab CI. This GitHub copy is a mirror; the working tree is at gitlab.alpinelinux.org/alpine/aports. ### How does a package move from testing into Alpine's repositories? Packages start in the `testing/` directory and are promoted afterwards, either to `main/` or to `community/`, following the policy of whichever one they land in. A package that has not moved within a 6 month period gets its maintainer notified, and it is removed after 9 months. ### What is the difference between the main and community repositories in aports? A package in main has to be reasonable to expect in a basic system and needs a developer assigned who can maintain it, while community holds the packages that do not belong in main and only need a maintainer. Both require test suites enabled if the source provides them. ### How do I turn on the git hooks in aports? The hooks live in the `.githooks/` directory and are off after a plain clone. Point Git at them with the local config command shown on the page, then commits go through them. ### Where should I submit a change to aports? As a merge request on GitLab at gitlab.alpinelinux.org/alpine/aports. The page also offers the mailing list at ~alpine/aports@lists.alpinelinux.org, but annotates that route as presently not functional, and the contributor guide on the Alpine wiki is linked from the same paragraph. ### Does the aports repository state a licence? No licence is named in the repository metadata and there is no licence file at the root of the tree. What is there is CODINGSTYLE.md, COMMITSTYLE.md, .editorconfig, .gitattributes and a .mailmap, so the licensing question is the one left open. ## Sources - [Official documentation](https://gitlab.alpinelinux.org/alpine/aports) - [Official README](https://github.com/alpinelinux/aports#readme) - [Project repository](https://github.com/alpinelinux/aports) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/alpinelinux-aports