When a release is triggered we parse each configuration file we find and check it for possible issues. These issues are broken down into two types - Errors and Warnings.
If any errors are found the release will fail and no packages will be built. Warnings on the other hand won't stop a release but should still be looked at.
On this page you will find
- A list of possible errors in a configuration
- Warnings that might be raised with one of your configurations
- How to validate you configuration before creating a release
- Other known issues which currently do not have validation checks against them
For more information on any of the issues it's a good idea to check full reference page to ensure you are using the correct key name and value type etc.
Unable to find any config files- Please see The basics - Where they live for how to name config files correctly
Invalid syntax- Configuration files must be valid YAML
<key> missing from config- The key stated is a required field but is missing
<key> must include at least on of: [value types]- Some key-values don't have a single required field but at least 1 of the mentioned fields must be included. See the correct section in the Full reference
<key> has no value- Any key included within a config must have a value. If the key is not required please omit the key instead of leaving it empty
<key> needs to be a <value-type>- Please ensure the value provided is the correct type as detailed on the Full reference page
name can only contain lowercase characters, numeric characters, hyphens, plus signs and full stops- The value for the name field can only contain lowercase characters, numeric characters, hyphens (
-), plus signs (
+) and full stops (
.). Regex used:
<field> must be one of - <choices>The field mentioned can only be set to once of the choices stated. Please see Valid choices on the full reference page
format is not valid for distribution- For example
debis not a valid format for
centos7. See Valid choices on the full reference page for details on which formats are valid for which distributions
Path <path> must be a relative path- Both the
sourcepath within the copy key-value and
filewithin the a commands key value must be relative paths from the base of the git repository
File <path> does not exist in repository- We were unable to find the referenced file. Please ensure the path is relative from the base of the git repository. This is an error if related to command
- file: ./pathfiles as these files are read before build
copy permissions must be valid chmod numerical value- The permissions key must be a valid numeric (octal) value
Unexpected error - ...- This is often caused by a value being the wrong data type. If you keep seeing this issue and are not sure what to do please contact us
yum/apt is not allowed in <section>- It is not possible to use
aptin any section except for
build. APT / YUM creates a lock during the install process on the end machine when you package is being install so it's not possible to use these commands.
service/systemctl is not allowed in <section>- Using
installsection does not interact with the system as expected. Top interface with the system please do so either before or after the install / upgrade.
For more information on any issue with keys please see their breakdown on the full reference page
<key> is not a valid field- The key provided is not a key we are expecting and will be ignored.
<field> missing. A default value will be used- The field is missing but a default is used. It's considered best practise to set these fields as the default is often incomplete or incorrect.
File <path> does not exist in repository- We were unable to find the referenced file. Please ensure the path is relative from the base of the git repository. Please ignore if the file or directory in question is created during the build.
rm should normally not be used in install- As the install process is done in an isolated environment and using
rmto remove files or directories may not actually remove the file as expected. If you want to delete files or directories it should be done in either the
Checking your config
When you visit a project page it will automatically check for config for any issues and let you know if there are any. A button will be displayed to the validate-config page for a full breakdown.
You can go directly to the validate-config page for any project at any time by adding
/validate-config onto the project page URL. The full URL will look something like:
https://app.pkgdeploy.com/<myorg>/<myproject>/validate-config # Swap <myorg> and <myproject> for the project you want to view
Other known issues
The below issues are do not currently have checks in place as part of the validation process but they may still cause your build to fail or your packages to not install as expected.
Errors which can happen irrelevant to the package format that is being created
tarcan not be used with relative paths.
tarwith to absolute paths may fail on the build machine is used in the
installsections. It's safer to use them in the
mv -fare used so the commands do not require user input
- The package builder uses minimal distributions. Software such as python / ruby is not installed by default so will need to be installed via
requiresin build or install
rmcommand should have -f to ensure it returns a 0 exit code if the file / directory does not exist
- User / group includes in copy section should generally be created in the main install. This is unless the user / group is created by another process
- When using
pipor any python virtual environment in the build section, you may need to use the
directorykey/value. This is because certain python modules in the
./bininject a shebang into the top of their file with an absolute path to the python interpreter. If the
directorykey/value is not specified this path could be different on the build machine vs. the end-user machine.
- When using
pipenvin the build section, you may need to use the
PIPENV_VENV_IN_PROJECT=1to ensure the virtual environment is created in the correct directory and is copied as part of the build and install process
- Exporting environmental variables may not work as expected. It is a better idea to set the environmental variable on the same line just before the command that the variable is intended for. E.g.
yum installcan't be used outside of build section. Please use requires - holding the yum lock - Use requires* NOQA
yum installin the build section must include
-yto not require any user input
- To write files use the
installsection. Writing files using
catand writing or appending with
>>will mean the package does not keep a record of the file being created and thus may not be removed when the package is uninstalled
- Writing to
/etc/yum.repos.d/as part of the install process will not register the repository before the package install starts. Add new repositories needs to be done manually before trying to install your package.
- 32-bit architecture (i686 / i386) has been dropped from RHEL 7 / CentOS 7+
sourcecommand cannot be used in build or install sections
apt-get installin the build section must include
-yto not require any user input
- license not set so
Unknownwill be used
- Maintainer not set so
Unknown <email@example.com>will be used. It's encouraged that the maintainer key/value is set in format
First Last <firstname.lastname@example.org>
- The debian build commands user make to build packages which require PKG Deploy to create a
Makefilein the root of your directory. If you already have a
Makefileat the root of your directory this will currently be overwritten
- 32-bit architecture (i386) has been dropped from Ubunutu 19.10+
- cat > /etc/apt/sources.list won't resolve before Requires # NOQA
- Writing to
/etc/apt/sources.listas part of the install process will not register the repository before the package install starts. Add new repositories needs to be done manually before trying to install your package.