xk6bundler is a CLI tool and GitHub Action makes bundle k6 with extensions as fast and easily as possible.
Features
- Build for multiple target platforms
- Create per platform
.tar.gz
archives for releases - Generate
Dockerfile
for Docker build/push - Guess reasonable default values
- Almost drop-in xk6 replacement
- Only one GitHub workflow file required to build and publish custom k6 bundle
For a real life example check k6-crocus and it's .github/workflows/xk6bundler.yml file
Table of Contents
The CLI tool and GitHub Action has same parameters. The main difference is how to pass the parameters. Another difference is that using CLI tool you may specify with
and platform
parameters multiple times, while using GitHub action you should specify these parameters only once, but you may use a whitespace separated list of values.
The following table show parameter names, CLI option flags and environment variable names for the default value of a given parameter:
Parameter | CLI | Environment |
---|---|---|
name |
-n, --name=name |
XK6BUNDLER_NAME |
version |
-v, --version=version |
XK6BUNDLER_VERSION |
with |
-w, --with=extension |
XK6BUNDLER_WITH |
markdown |
-m, --markdown=path |
XK6BUNDLER_MARKDOWN |
platform |
-p, --platform=target |
XK6BUNDLER_PLATFORM |
output |
-o, --output=path |
XK6BUNDLER_OUTPUT |
archive |
-a, --archive=path |
XK6BUNDLER_ARCHIVE |
k6_repo |
--k6-repo=repo |
XK6BUNDLER_K6_REPO |
k6_version |
--k6-version=version |
XK6BUNDLER_K6_VERSION |
Short name of the bundle. Optional, if missing then xk6bunder will try to guess from git remote or from current directory name.
Bundle version. Optional, if missing then xk6bundler will try to guess from GITHUB_REF
or default to SNAPSHOT
.
xk6 extension to add in module[@version][=replacement]
format. When using CLI, it can be used multiple times to add extensions by specifying the Go module name and optionally its version, similar to go get. Module name is required, but specific version and/or local replacement are optional. Replacement path must be absolute. When using GitHub Action, it can contains whilespace separated list of modules. Optional, if missing then no xk6 extension will be bundled.
Extract xk6 extension list from markdown code blocks marked with language xk6
. Multiple xk6
code blocks will merge to single extension list. Each line in code block contains extension in module[@version][=replacement]
format (see with).
Target platform in os/arch
format. When using CLI, it can be used multiple times to add target platform. When using GitHub Action, it can contains whilespace separated list of target platforms. Optinal, default value is linux/amd64 windows/amd64 darwin/amd64
Go template of output file path. Optional, default value is dist/{{.Name}}_{{.Os}}_{{.Arch}}/k6{{.Ext}}
The following template variables available in template:
Variable | Descripion |
---|---|
Os |
OS name (values defined by GOOS ) |
Arch |
hardware architecture (values defined by GOARCH ) |
Ext |
.exe on windows empty otherwise |
Name |
bundle name |
Version |
bundle version |
You can use slim-sprig template function library as well.
Go template of archive (.tar.gz) file path. Optional, default value is dist/{{.Name}}_{{.Version}}_{{.Os}}_{{.Arch}}.tar.gz
The following template variables available in template:
Variable | Descripion |
---|---|
Os |
OS name (values defined by GOOS ) |
Arch |
hardware architecture (values defined by GOARCH ) |
Ext |
.exe on windows empty otherwise |
Name |
bundle name |
Version |
bundle version |
You can use slim-sprig template function library as well.
Build using a k6 fork repository. The repo can be a remote repository or local directory path.
The core k6 version to build. Optional, if missing then latest
will be used.
For using xk6bundler as GitHub Action, you should include a workflow step with uses: szkiba/xk6bundler@v0
- name: Build
id: build
uses: szkiba/xk6bundler@v0
with:
platform: linux/amd64 windows/amd64
with: |
github.com/szkiba/[email protected]
github.com/szkiba/[email protected]
github.com/szkiba/[email protected]
The xk6bundler GitHub Action outputs the following variables:
Short name of the bundle.
Bundle version.
Generated Dockerfile path.
Docker context directory path. Can be use as context
parameter for Docker build action (assuming build
is the id of the xk6bundler step):
- name: Docker build and push
uses: docker/build-push-action@v2
with:
context: ./${{ steps.build.outputs.dockerdir }}
The
./
prefix required, it will tell to Docker action that this is a local path (not an URL).
See samples/sample-dockerhub-workflow.yml for complete example.
The xk6bundler GitHub Action generates result by default in dist
directory of the current workspace. You can publish generated archive (.tar.gz) files using any thirdpary release GitHub Action.
Sample workflow file for publishing xk6 bundle on GitHub releases page: samples/sample-workflow.yml. Put this file in to .github/workflows
directory.
If target platforms include linux/amd64
then xk6bundler will generate Dockerfile
next to linux/amd64
platform's output file. You can use it to build Docker image and push it for example to Docker Hub registry (or to any other).
Sample workflow file for publishing xk6 bundle on GitHub releases page and on Docker Hub registry: samples/sample-dockerhub-workflow.yml. Put this file in to .github/workflows
directory.
You can install the pre-compiled binary or use Docker.
Download the pre-compiled binaries from the releases page and copy to the desired location.
If you have Go environment set up, you can build xk6bundler from source by running:
go get github.com/szkiba/xk6bundler/cmd/xk6bundler
Binary would be installed to $GOPATH/bin/xk6bundler.
You can also use it within a Docker container. To do that, you'll need to execute the following:
docker run szkiba/xk6bundler
To verify your installation, use the xk6bundler -V
command:
$ xk6bundler -V
xk6bundler/0.1.0 linux/amd64
You should see xk6bundler/VERSION
in the output.
To print usage information, use the xk6bundler --help
command.