PKG Deploy

Docs

Common issues

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

Validation errors

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: [a-z0-9-.+]

  • <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 deb is 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 source path within the copy key-value and file within 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: ./path files 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 yum / apt in 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 systemctl / service in the install section does not interact with the system as expected. Top interface with the system please do so either before or after the install / upgrade.

Validation warnings

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 rm to 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 after_install or after_upgrade sections.

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.

General

Errors which can happen irrelevant to the package format that is being created

Errors

  • cp, mv, rm, mkdir, chown, chmod, unzip, tar can not be used with relative paths.
  • Using cp, mv, rm, mkdir, chown, chmod, unzip, tar with to absolute paths may fail on the build machine is used in the build or install sections. It's safer to use them in the after_install or after_upgrade sections
  • Ensure rm -f and mv -f are used so the commands do not require user input

Warnings

  • The package builder uses minimal distributions. Software such as python / ruby is not installed by default so will need to be installed via requires in build or install
  • Any rm command 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 pip or any python virtual environment in the build section, you may need to use the directory key/value. This is because certain python modules in the./bin inject a shebang into the top of their file with an absolute path to the python interpreter. If the directory key/value is not specified this path could be different on the build machine vs. the end-user machine.
  • When using pipenv in the build section, you may need to use the directory key/value and PIPENV_VENV_IN_PROJECT=1 to 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. MYENV=test ./command.sh

RPM only

Errors

  • yum install can't be used outside of build section. Please use requires - holding the yum lock - Use requires* NOQA
  • yum install in the build section must include -y to not require any user input

Warnings

  • To write files use the copy key/value in install section. Writing files using echo, touch or cat and writing or appending with > or >> 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+

DEB only:

Errors

  • source command cannot be used in build or install sections
  • apt install / apt-get install in the build section must include -y to not require any user input

Warnings

  • license not set so Unknown will be used
  • Maintainer not set so Unknown <[email protected]> will be used. It's encouraged that the maintainer key/value is set in format First Last <[email protected]>
  • The debian build commands user make to build packages which require PKG Deploy to create a Makefile in the root of your directory. If you already have a Makefile at 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.list 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.