In this document there is a breakdown of all of the different fields that are available within a configuration file, their value type, if required and, a description.
You can see a complete configuration in our full YAML example.
Full list of key-values
requires(list of strings)
copy(list of key-values)
source(string - relative path)
destination(string - absolute path)
permissions(integer or string)
commands(string or list of key-value - commands)
before_install(string or list of key-value - commands)
after_install(string or list of key-value - commands)
before_upgrade(string or list of key-value - commands)
after_upgrade(string or list of key-value - commands)
before_uninstall(string or list of key-value - commands)
after_uninstall(string or list of key-value - commands)
It is always considered a good idea to add as many of the key-values as possible.
For example, while they are not required fields, fields such as
maintainer give people a lot more information about your package which can only be beneficial to end users, even if they are just within your organisation.
||Name of the package which is used when installing via APT or YUM. It can only contain lowercase characters, numeric characters, hyphens (
||The type of package you want to create. Must be either
|distribution||string (multi-choice)||No||The specific Linux distribution the software will be built on. See the valid choices below. Defaults to
|architecture||string (multi-choice)||No||What architecture your package supports. See the valid choices below. Defaults to
|description||string||No||A full description of the software packaged. Use YAML multi-line strings to have a multi-line description|
|url||string||No||The full URL for more information about your software. Can just be an upstream project website|
|license||string||No||Short License identifier for the license you want to release your code under. It will default to 'Unknown''|
|maintainer||string||No||Must be in format "Name <[email protected]>". It will default to "Unknown <[email protected]>" if not supplied|
|build||key-value||No||See build section|
||See install section|
|before_install||string or list of key-values||No||See commands section|
|after_install||string or list of key-values||No||See commands section|
|before_upgrade||string or list of key-values||No||See commands section|
|after_upgrade||string or list of key-values||No||See commands section|
|before_uninstall||string or list of key-values||No||See commands section|
|after_uninstall||string or list of key-values||No||See commands section|
- format -
- distribution (format dependant):
- deb -
debian10- Defaults to
ubuntu18if not supplied
- rpm -
fedora32- Defaults to
centos7is not supplied
- deb -
- architecture -
any- Defaults to
64-bitif not supplied
- Note: These architectures are translated into the correct but less human readable values such as i386, x86_64, amd64 etc
|requires||list of strings||No||A list of any packages that are required to run the build commands. You need to assume the build server is fresh minimal install with no applications installed.
|directory||string||No||The directory the code will be built in. This can be important if a build step injects a path to your code such as in a shebang, often the case when using virtual environments in python or npm node_modules. If needed it is often set to a location code is copied to in your install step|
|commands||string or list of key-values||Yes||See commands section|
|requires||list of strings||No||A list of any packages that your application depends on to run.
|user||String||No*||Creates a user with this name as part of the install|
|group||String||No*||Creates a group with this name as part of the install|
|copy||list of key-values||No*||See copy section|
|commands||string or list of key-values||No*||See commands section|
* One of these fields is required. While each of the keys is marked as not required you must include at least one of
commands within the install section.
For a more in-depth breakdown check out the Copying code page
Copy requires a list of key-values. Each of these key-values lists can have the following keys
|source||string (relative path)||Yes||Relative path to a file or directory in your git repository you want to copy|
|destination||String (absolute path)||Yes||Absolute path to the install location on the end-user machine|
|user||String||No||The user that should own what is being copied|
|group||String||No||The group that should own what is being copied|
|permissions||String||No||chmod numeric notation of the permissions given to what is being copied. E.g.
For a more in-depth breakdown check out the Running commands page
Any command section may be a single line string, multi-line string or a list of key-values.
The keys in the table below are only needed if you want to use a list, strings have no key-values.
|run||string||No*||Single string command|
|file||String (absolute path)||No*||Relative path to a file with commands that need to be run. Allows for commands to be used across multiple configuration files|
* One of these fields is required if using a list. While neither of the keys is marked as required you must have at least one of
file in a command section if you use a list and not a string.
requires key-value allows you to specify what other software your application depends on. It works slightly differently depending on if it is being used in the
Each package is individually installed on the build server one at a time via an APT/YUM command in the order they are specified. This allows one requirement to depend on another. For example, you can install a package repository before then installing a package from that repository.
rpm builds, the
build requires also supports be HTTP URL's as they are supported by
To use HTTP URL's in when building
deb packages a combination of
dpkg can be used within the
Package dependencies are directly controlled via APT/YUM. as dependency management on the end-user machine can be far more complicated. This is because the package manager needs more control in case a package install fails and it needs to remove all dependencies etc.
Full YAML Example
The below example is just to show a technically valid configuration file. It is not intended to be used but includes all of the different fields available. Where a key supports multiple value types we have included examples of the different types.
For more in-depth examples with full explanations please see the examples page
name: my-app format: deb distribution: ubuntu18 architecture: amd64 description: New awesome application url: https://www.pkgdeploy.com license: GPLv3 maintainer: MyApp Engineers <[email protected]> build: directory: /var/lib/myapp/ requires: - python36-devel - python36-pip commands: | # Commands multi line string python3.6 -m venv ./venv/ ./venv/bin/pip install -r requirements.txt install: requires: - python36 - nginx user: myuser group: mygroup copy: - source: ./ destination: /var/lib/myapp/ user: myuser group: mygroup permissions: 0755 - source: myapp.service destination: /etc/systemd/system/myapp.service commands: | curl http://example.com -o /var/lib/myapp/example.txt -s before_install: | # Commands multi line string export LANG=en_US.UTF-8 export LANGUAGE=en_US:en export LC_ALL=en_US.UTF-8 before_upgrade: | # Commands multi line string rm -rf /var/lib/myapp/old-logs/ after_install: # Commands list of key values with run keys - run: nginx -s reload - run: systemctl enable myapp - run: systemctl start myapp after_upgrade: # Commands list of key values with file and run keys - file: ./scripts/upgrade.sh - run: systemctl restart myapp before_uninstall: systemctl stop myapp # Command single line string after_uninstall: usermod -L myuser # Command single line string