= GitHub Action: Setup Alpine Linux :proj-name: setup-alpine :gh-name: jirutka/{proj-name} :gh-branch: v1 :action-ref: {gh-name}@{gh-branch} :alpine-latest: v3.15 :apk-tools: https://gitlab.alpinelinux.org/alpine/apk-tools/[apk-tools]
A https://github.com/features/actions[GitHub Action] to easily set up and use a chroot-based footnote:[If you don’t know what https://en.wikipedia.org/wiki/Chroot[chroot] is, think of it as a very simple container. It’s one of the cornerstones of containers and the only one that is actually needed for this use case.] https://alpinelinux.org/[Alpine Linux] environment in your workflows and emulate any supported CPU architecture (using QEMU).
runs-on: ubuntu-latest steps:
uses: {action-ref} with: branch: {alpine-latest}
See <<examples, more examples>>…
== Highlights
Easy to use and flexible
Add one step uses: {action-ref} to set up the Alpine environment, for the next steps that should run in this environment, specify shell: alpine.sh {0}. See <
Emulation of non-x86 architectures
** This couldn’t be easier; just specify input parameter <
No hassle with Docker images You don’t have to write any Dockerfiles, for example, to cross-compile Rust crates with C dependencies.footnote:[The popular https://github.com/cross-rs/cross[cross] tool used by https://github.com/actions-rs/cargo#cross-compilation[actions-rs/cargo] action doesn’t allow you to easily install additional packages or whatever needed for building your crate without creating, build and maintaining custom Docker images (https://github.com/cross-rs/cross/issues/281[cross-rs/cross#281]). This just impose unnecessary complexity and boilerplate.] No, you really don’t need any so-called “official” Docker image for gcc, nodejs, python or whatever you need… just install it using https://www.mankier.com/8/apk[apk] from https://pkgs.alpinelinux.org/packages[Alpine packages]. It is fast, really fast!
Always up to date environment The whole environment, all packages, are always installed directly from the Alpine Linux’s official repositories using {apk-tools} (Alpine’s package manager). There’s no intermediate layer that tends to lang behind with security fixes (such as Docker images). — You might be thinking, isn’t that slow? No, it’s faster than pulling a Docker image! No, you really don’t need any Docker image to get a stable build environment. Alpine Linux provides stable https://alpinelinux.org/releases/[releases] (branches); these get just (security) fixes, no breaking changes.
It’s simple and lightweight ** You don’t have to worry about that on a hosted CI service, but still… This action is written in ~220 LoC and uses only basic Unix tools (chroot, mount, wget, Bash, …) and {apk-tools} (Alpine’s package manager). That’s it.
== Parameters
=== Inputs
apk-tools-url::
URL of the apk-tools static binary to use.
It must end with #!sha256! followed by a SHA-256 hash of the file.
This should normally be left at the default value.
+
Default: see link:action.yml[]
[[arch]] arch::
CPU architecture to emulate using https://www.qemu.org/docs/master/user/main.html[QEMU user space emulator].
Allowed values are: x86_64 (native), x86 (native), aarch64, armhf footnote:[armhf is armv6 with hard-float.], armv7, ppc64le, riscv64 footnote:[riscv64 is available only for branch edge for now.], and s390x.
+
Default: x86_64
branch::
Alpine branch (aka release) to install: vMAJOR.MINOR, latest-stable, or edge.
+
Example: {alpine-latest} +
Default: latest-stable
extra-keys::
A list of paths of additional trusted keys (for installing packages from the extra-repositories) to copy into /etc/apk/keys/.
The paths should be relative to the workspace directory (the default location of your repository when using the checkout action).
+
Example: .keys/pkgs@example.org-56d0d9fd.rsa.pub
extra-repositories::
A list of additional Alpine repositories to add into /etc/apk/repositories (Alpine’s official main and community repositories are always added).
+
Example: http://dl-cdn.alpinelinux.org/alpine/edge/testing
mirror-url::
URL of an Alpine Linux mirror to fetch packages from.
+
Default: http://dl-cdn.alpinelinux.org/alpine
packages::
A list of Alpine packages to install.
+
Example: build-base openssh-client +
Default: no extra packages
shell-name::
Name of the script to run sh in the Alpine chroot that will be added to GITHUB_PATH.
This name should be used in jobs.<job_id>.steps[*].shell (e.g. shell: alpine.sh {0}) to run the step’s script in the chroot.
+
Default: alpine.sh
volumes::
A list of directories on the host system to mount bind into the chroot.
You can specify the source and destination path: <src-dir>:<dest-dir>.
The <src-dir> is an absolute path of existing directory on the host system, <dest-dir> is an absolute path in the chroot (it will be created if doesn’t exist).
You can omit the latter if they're the same.
+
Please note that /home/runner/work (where’s your workspace located) is always mounted, don’t specify it here.
+
Example: ${{ steps.alpine-aarch64.outputs.root-path }}:/mnt/alpine-aarch64
=== Outputs
root-path:: Path to the created Alpine root directory.
[[examples]] == Usage examples
=== Basic usage
runs-on: ubuntu-latest steps:
uses: actions/checkout@v2
name: Setup latest Alpine Linux uses: {action-ref}
name: Run script inside Alpine chroot as root run: | cat /etc/alpine-release apk add nodejs npm shell: alpine.sh --root {0}
name: Run script inside Alpine chroot as the default user (unprivileged) run: | ls -la # as you would expect, you're in your workspace directory npm build shell: alpine.sh {0}
=== Set up Alpine with specified packages
=== Set up and use Alpine for a different CPU architecture
runs-on: ubuntu-latest steps:
name: Setup Alpine Linux {alpine-latest} for aarch64 uses: {action-ref} with: arch: aarch64 branch: {alpine-latest}
=== Set up Alpine with packages from the testing repository
=== Set up and use multiple Alpine environments in a single job
runs-on: ubuntu-latest steps:
name: Setup latest Alpine Linux for x86_64 uses: {action-ref} with: shell-name: alpine-x86_64.sh
name: Setup latest Alpine Linux for aarch64 uses: {action-ref} with: arch: aarch64 shell-name: alpine-aarch64.sh
name: Run script inside Alpine chroot run: uname -m shell: alpine-x86_64.sh {0}
name: Run script inside Alpine chroot with aarch64 emulation run: uname -m shell: alpine-aarch64.sh {0}
[[cross-compile-rust]] === Cross-compile Rust application with system libraries
runs-on: ubuntu-latest strategy: matrix: include:
rust-target: aarch64-unknown-linux-musl os-arch: aarch64 env: CROSS_SYSROOT: /mnt/alpine-${{ matrix.os-arch }} steps:
uses: actions/checkout@v1
name: Set up Alpine Linux for ${{ matrix.os-arch }} (target arch) id: alpine-target uses: {action-ref} with: arch: ${{ matrix.os-arch }} branch: edge packages: > dbus-dev dbus-static shell-name: alpine-target.sh
name: Set up Alpine Linux for x86_64 (build arch) uses: {action-ref} with: arch: x86_64 packages: > build-base pkgconf lld rustup volumes: ${{ steps.alpine-target.outputs.root-path }}:${{ env.CROSS_SYSROOT }} shell-name: alpine.sh
name: Install Rust stable toolchain via rustup run: rustup-init --target ${{ matrix.rust-target }} --default-toolchain stable --profile minimal -y shell: alpine.sh {0}
name: Build statically linked binary env: CARGO_BUILD_TARGET: ${{ matrix.rust-target }} CARGO_PROFILE_RELEASE_STRIP: symbols PKG_CONFIG_ALL_STATIC: '1' PKG_CONFIG_LIBDIR: ${{ env.CROSS_SYSROOT }}/usr/lib/pkgconfig RUSTFLAGS: -C linker=/usr/bin/ld.lld SYSROOT: /dummy # workaround for https://github.com/rust-lang/pkg-config-rs/issues/102 run: |
echo -e '#!/bin/sh\nPKG_CONFIG_SYSROOT_DIR=${{ env.CROSS_SYSROOT }} exec pkgconf "$@"' \ | install -m755 /dev/stdin pkg-config export PKG_CONFIG="$(pwd)/pkg-config" cargo build --release --locked --verbose shell: alpine.sh {0}
== History
This action is an evolution of the https://github.com/alpinelinux/alpine-chroot-install[alpine-chroot-install] script I originally wrote for Travis CI in 2016. The implementation is principally the same, but tailored to GitHub Actions. It’s so simple and fast thanks to how awesome {apk-tools} is!
== License
This project is licensed under http://opensource.org/licenses/MIT/[MIT License]. For the full text of the license, see the link:LICENSE[LICENSE] file.