• Trigger Jenkins builds when pushing changes to the repository
• Build packages using different branches
• Purpose of the scripts
• Customization and Configuration
• Tips and Tricks

---

Create a new Jenkins job for your own Debian package

The easiest way to add further Jenkins jobs for additional Debian packages is using the existing ones as input. Just use the exisiting jenkins-debian-glue-source job as input for your new *-source job and the jenkins-debian-glue-binaries one as input for your new *-binaries job:

Do not forget to adjust the repository URL accordingly for your own package:

Trigger Jenkins builds when pushing changes to the repository

Once you're happy with the way your Jenkins jobs work you usually don't want to click on 'Build now' manually whenever you want to trigger the build process. Instead let's build Debian packages whenever changes are pushed into your repository.

To avoid polling for updates in VCS trigger the build remotely from your version control system:

• If you're using Github for your Git repository the easiest way to get remote trigger actions working is using the Github Plugin with its "Build when a change is pushed to GitHub" option.
• If you don't use Github but have your own git repository hosting then enable "Trigger builds remotely (e.g., from scripts)" option in the Build Triggers section. Set a user-defined authentication token so only you and your installed hook scripts know how to trigger such a build. The svn and git directories of the jenkins-debian-glue source provide examples for VCS hooks to trigger remote builds on each commit. (While this approach requires a bit more effort to set up you're much more flexible as you can customize your hooks as you like. For example building only specific branches, providing parameterized build settings and triggering multiple (independent) Jenkins jobs

Build packages using different branches

You might want to build your Debian package based on a specific branch. For Git you could hardcode the branch(es) inside the 'Branches to build' setting. But you are much more flexible by using parameterized builds. Depending on whether you use Git or Subversion adjust the Jenkins job accordingly:

If you're using Git then enable the 'This build is parameterized' with the 'String parameter' option in the source job. Add String Parameter settings as follows:

Name: branch
Default value: master
Description: branch to build (trunk, tags/...)

Then adjust the 'Branches to build' SCM settings:

If you're using Subversion instead then enable the 'This build is parameterized' with the 'List Subversion tags (and more)' option in the source job. An example configuration looks like:

DONE! Now you should be able to choose the branch that should be used for building the Debian source package.

Put different branches in different repos

Additionally to building Debian package based on a specific branch, you might want that built packages are put in a branch-based repository as well. To achieve that, start with adjusting the Artifact Deployer-Configuration like this:

You should also choose "Trigger parameterized build on other projects" and add "Current build parameters" to the parameters. This will make sure, that the chosen branch is passed to the binary job. You can remove the usual "Build after other projects are built" trigger.

Next, proceed with the binary job. Start making it parameterized and accepting the branch parameter as done in the source job.

Now edit the build commands to be as following:

  rm -rf ./* || true
  export sources="${JENKINS_HOME}/userContent/${branch}/${JOB_NAME%-binaries*}-source"
  export REPOS="${JOB_NAME%-binaries*}-${branch}-${distribution}"
  /usr/bin/generate-reprepro-codename "${REPOS}"

  /usr/bin/build-and-provide-package
  

Thats it. If you now trigger a build for your source job, it will ask your for the branch and will put the resulting binaries and sources into a branch-specific repository.

Purpose of the scripts

The following scripts are provided by jenkins-debian-glue:

• build-and-provide-package: uses the Debian package source files (provided and derived from the according *-source Jenkins job) for building Debian binary package(s) for the specified $architecture of the matrix build using cowbuilder. The resulting binary package(s) will be installed in the repository (managed through reprepro) to provide it for usage via APT.
• generate-git-snapshot: generates a snapshot version of the Debian package using git-dch to generate debian/changelog containing a list of changes
• generate-reprepro-codename: takes a repository/codename as command line option and adds an according repository/codename definition to /srv/repository/conf/distributions (iff the codename is not present yet).
• generate-svn-snapshot: generates a snapshot version of a Debian package using svn log, svn2cl and some dirty shell magic to get a useful debian/changelog.
• increase-version-number: takes a version number as command line argument and raises the version number for usage inside as a new snapshot version. Nowadays the script just adds '+0' to the version number, so when running the script with input '0.42' the output will be '0.42+0'. (Disclaimer: This script used to be more sophisticated but turned out to fail in some situations, the +0 approach usually just works and the script is there to provide a central place to handle version number management.)
• lintian-junit-report: run Debian package checks using lintian and report results in xUnit/JUnit format (and also provide a plaintext copy of the output inside file lintian.txt).
• repository_checker: provides simple access to codename/repository and package listings (without the need to know how to handle the reprepro repository tool) as well as an option to verify whether Debian source packages match with binary package versions.

Customization and Configuration

jenkins-debian-glue and its scripts can be customized mainly through several environment variables.

You can either set environment variables system wide or inside Jenkins jobs (use export VARIABLE=SETTING in the 'Execute shell' step accordingly).

System wide via /etc/jenkins/debian_glue

The following settings are supposed to be configured in /etc/jenkins/debian_glue:

• KEY_ID: setting this variable automatically signs repository with the specified GnuPG key ID. Please notice that already existing repositories won't be touched. If you set up a GnuPG key and the KEY_ID configuration after a repository was created (will be done on first execution of build-and-provide-package for a given binary job) make sure to manually add SignWith: ${KEY_ID} to your repository configuration ("/srv/repository/conf/distributions/" by default).
• MAIN_ARCHITECTURE: if you are building Debian packages for more than one architecture you can control which architecture should be used as main one. The main architecture setting controls which architecture should be used as the one providing the architecture independent Debian packages (like foobar0.42-1all.deb). If unset it defaults to the architecture your build system is running.
• REPOSITORY: the directory where your Debian repository will be placed at. Defaults to "/srv/repository/".
• RELEASE_REPOSITORY: the directory where reprepro's release repository is located. Relevant only if the $release setting is in use. If unset defaults to ${REPOSITORY}/release/${release}. Available since jenkins-debian-glue v0.5.0.
• TRUNK_RELEASE: if you want to get a copy of all generated Debian packages in one single distribution you can set TRUNK_RELEASE to something like "release-trunk". The repository will be automatically set up if it doesn't exist yet.

Supported in build-and-provide-package

The following settings are supported by build-and-provide-package:

• architecture: controls for which architectures Debian packages should be built.
• distribution: controls Debian version that should be used for the cowbuilder environment (defaults to the host's distribution if unset).
• release: install Debian package in repository name as specified via "$release" instead of the default (being $REPOS), see "Can I collect multiple Debian packages in one single repository?" in the FAQ section for further details.
• BASE_PATH: use specified directory as base directory for further actions. Defaults to "${WORKSPACE}" if unset. Adjust it if you e.g. have a customized "Target directory" in the "Copy artifacts from another project" configuration.
• BUILD_ONLY: execute the steps building Debian binary package(s) but skip the repository setup/inclusion steps (useful for building the package(s) on slave nodes and including the result on a different node later then)
• COMPONENTS: the specified repository components will be enabled when creating a new cowbuilder base.cow. If unset defaults to pbuilder's defaults (the underlying system of cowbuilder). Notice that on Ubuntu systems COMPONENTS will be automatically set to "main universe" (if COMPONENTS isn't set yet) to work around a cowdancer issue.
• COWBUILDER_BASE: set path for cowbuilder's base.cow, defaults to /var/cache/pbuilder/base-${COWBUILDER_DIST}-${arch}.cow/ whereas COWBUILDER_DIST depends on its according variable and arch depends on architecture (though doesn't match it if it's set to "all").
• COWBUILDER_DIST: distribution that should be used for creating the cowbuilder base.cow. If distribution is set COWBUILDER_DIST defaults to that, otherwise defaults to the currently running distribution and if that can't be determined then falls back to "sid" (being Debian/unstable).
• PROVIDE_ONLY: skip the steps building Debian binary package(s) and just run the repository setup/inclusion steps (useful if building the package(s) takes place on slave nodes and the result should by included in repository/repositories on a specific node then)
• REMOVE_FROM_RELEASE: remove packages from a $release before processing incoming. This allows to rebuild and provide versions already existent in the release repository they are built for. (Available since jenkins-debian-glue v0.6.0)
• REPOS: controls the repository name used for the binary job. Defaults to the Jenkins job name without trailing "-binaries" and without trailing "-repos".
• SKIP_PACKAGE_FROM_REMOVAL: skip specific packages from repository removal (available since jenkins-debian-glue v0.6.0)
• SUDO_CMD: if this variable is set then reprepro and related actions will be executed under $SUDO_CMD. If the jenkins user doesn't have write permissions to the repository and related settings then you might consider setting "export SUDO_CMD=sudo" in your Build step.
• USE_FREIGHT: if this variable is set then Freight will be used instead of Reprepro as package repository management tool. With the advantage, that you are able to keep multiple versions of a Debian package in the repository. By default, packages will be stored in /var/lib/freight and /var/cache/freight, as mentioned in the Freight documentation. You can customize the paths using the variables FREIGHT_BASE and FREIGHT_REPOSITORY. Note: you need freight to be installed on your system.
• FREIGHT_BASE: the base path under which freight repositories should be created. Eg. set this to /srv/freight and you will end up with /srv/freight/default as the default freight destination. See FREIGHT_REPOSITORY for further customization.
• FREIGHT_REPOSITORY: customize the fright repository name. If set and FREIGHT_BASE is not set, packages will end up in /srv/freight/$FREIGHT_REPOSITORY. If FREIGHT_BASE is set, you would end up with a directory structure of $FREIGHT_BASE/FREIGHT_REPOSITORY.

Supported in generate-git-snapshot

The following settings are supported by generate-git-snapshot:

• DEBEMAIL: user configuration to be used for generating new entries in debian/changelog (defaults to "jenkins-debian-glue Autobuilder <jenkins@example.org>")
• DCH_OPTS: use custom git-dch options instead of the defaults.
• DCH_EXTRA_OPTS: use additional custom git-dch options.
• PRE_SOURCE_HOOK: if set the script pointed by PRE_SOURCE_HOOK will be executed before generation of the Debian source package. (Available since jenkins-debian-glue v0.6.0)
• SKIP_DCH: do not modify debian/changelog at all, e.g. to build a branch as-is (available since jenkins-debian-glue v0.4.0)
• DCH_CHANGELOG_FILE: if set the changelog file will be read from the specified location. Needed if the (original) debian folder is not ./debian. (available since jenkins-debian-glue v0.18.0)

Supported in generate-reprepro-codename

The following settings are supported by generate-reprepro-codename:

• SUDO_CMD: if this variable is set then reprepro and related actions will be executed under $SUDO_CMD. If the jenkins user doesn't have write permissions to the repository and related settings then you might consider setting "export SUDO_CMD=sudo" in your Build step.

Supported in generate-svn-snapshot

The following settings are supported by generate-svn-snapshot:

• DEBEMAIL: user configuration to be used for generating new entries in debian/changelog (defaults to "jenkins-debian-glue Autobuilder <jenkins@example.org>")
• PRE_SOURCE_HOOK: if set the script pointed by PRE_SOURCE_HOOK will be executed before generation of the Debian source package. (Available since jenkins-debian-glue v0.6.0)

Tips and Tricks

• Reduce disk usage: enable "Discard Old Builds" and set "Max # of builds to keep" to something like 15 to keep disk usage at a sane level.
• Install and use the Timestamper Plugin to get the 'Add timestamps to the Console Output' option in your Jenkins job configuration. This is very useful for tracing performance issues and timing problems.
• Install and use the Configuration Slicing Plugin to perform mass configuration of your source and binaries jobs.

---