This script is a Git and Subversion hook. Any commit or push of a new version will upload that version of code in the SWAMP. Results are viewable from the SWAMP website.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
config
.gitattributes
LICENSE
README-Development.adoc
README.adoc
RELEASE_NOTES.md
TODO.txt

README.adoc

SWAMP Version Control Systems Hook

1. Introduction

Version control systems (VCM’s) are designed to help manage code across multiple versions, allowing you to safely fall back on other versions if anything happens to your code, or reference older versions to compare your code as it develops. This script is designed for Git and Subversion. Once installed, this script will cause any commit or push to upload your package to the mir-swamp, https://www.mir-swamp.org, or any other swamp you configure, and run an assessment on it.

2. Prerequisites

The usage of this plugin requires that you already have the following:

  • Git or Subversion is installed on your computer, as well as some repository to use

  • A valid SWAMP account. If you do not have an account, go to https://continuousassurance.org to register.

3. Installation

To install the git hook, run the installer script using the following options:

Parameter Description

Select type of VCS System

--git

Install the hook for git

--svn

Install the hook for SVN

Select one or more of the folowing

--commit

Installs the commit version of the script - commits will trigger uploading (default)

--push

Installs the push version of the script - receiving a push will trigger uploading (only allowed if using git)

Optional

--force

Overrides any existing files inside your .git/hooks directory on installation

--update

Update an existing hook with a new version of the SCMS plugin components. This updates the components of the plugin. This will not over-write or destroy any configuration files. The process will create some '.instnew' suffix files of sample configuration files and the git hook itself. You should examine those '.instnew' files to see if any upgrades should be made to your existing configuration files or git hook file.

Miscellaneous Options

--help

Prints a help menu to console, then exits

--version

Prints the version string of the installer, then exits

--print-projects

Prints out your available projects for use in the configuration files (see below)

--print-platforms

Prints out all available platforms for use in the configuration files (see below)

--print-tools

Prints out all available tools for use in the configuration files (see below)

--http_proxy=

Set a http_proxy for plugin installation.

--https_proxy=

Set a http_proxy for plugin installation.

--java_home=

Set a java dir to provide java-8 for plugin installation.

Your environment can be setup to use a particular java by setting JAVA_HOME to the root of the java installed, and then adding $JAVA_HOME/bin to your PATH. This can be inconvenient or problematic in situations; instead of modifying your environment, the plugin can be configured to use the correct version of java at all times.

To configure the java version used by the plugin, use the JAVA_HOME configuration option. This option exists in the hook\SWAMP_Uploader/uploaderConfig.conf file. On a redhat-like system, such as fedora, rhel, scientific, or centos, add: JAVA_HOME=/usr/lib/jvm/java-1.8.0-openjdk On a debian-like system, such as debian or ubuntu, add: JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

The correct version of java must be available and configured, either in the environment or the config file.

For example, to add the SWAMP hook to an existing git workspace:

cd my-git-workspace
/path-to/swamp-scms-plugin/bin/installer.pl --git .
## Setup configuration
your-editor .git/hooks/SWAMP_Uploader/uploadConfig.conf
## Setup SWAMP credentials
your-editor .git/hooks/SWAMP_Uploader/uploadCredentials.conf

4. Configuring the Hook

The SWAMP hook must be configured before use. This configuration can be modified by altering the configuration files below.
If you are calling the script directly, you can set the values on the command line using --opt-name. The value in parentheses is the short command line option name.

4.1. In .git/hooks/SWAMP_Uploader/uploaderConfig.conf

Parameter Description

Assessment Options

platform (-p)

The name of the platforms used in the assessment For a full list of platforms, run hooks/SWAMP_Uploader/uploadPackage.pl --print-platforms Enter the platform names desired separated by commas (ex. platform=Red Hat Enterprise Linux 64-bit, Scientific Linux 64-bit,Centos Linux, etc.)

project

The name of the project that the package will be uploaded to The name 'MyProject' is the name of the project which every SWAMP account has available to it in the stock configuration. If you have created other SWAMP projects, or joined another SWAMP projects, those are also valid For a full list of projects available to you, run hooks/SWAMP_Uploader/SWAMP_Uploader/uploadPackage.pl --print-projects

tool (-t)

The tool names used for the assessment For a full list of tools, run hooks/SWAMP_Uploader/SWAMP_Uploader/uploadPackage.pl --print-tools Enter the tool names desired separated by commas (ex. tool=findbugs,errorprone, checkstyle, etc.) Tool names are case sensitive; use --print-tools output exactly!

Runtime Options

allowed-branches

Specify the branches that should be submitted to the SWAMP. Specify multiply branches separated by commas (ex. allowed-branches=master,branch01, branch02) If not specified, the default is to only submit the master branch.

assess

If assess=0 is specified, no assessment will be run. The package will still be uploaded, and if the new-package-dir option is specified, the package will still be stored in the specified directory.

new-package-dir

The directory to place the archived package and configuration file after the upload is complete. If not specified, the package will be deleted after uploading.

run-all-commits

Specific to the receive hook If run-all-commits=1 is specified, all commits since the last push will be uploaded and assessed. By default, this is disabled, and only the current commit or push will be uploaded and assessed.

upload

If you set upload=0 in the configurations, no upload to the SWAMP will occur. The script may still create a package for you if output-dir is specified. If not, the program will exit without doing anything. Useful if you want to temporarily disable this script.

File Directories

config-file (-c)

The location of the configuration file for the hook. If not specified, the default is in the same directory as uploadPackage.pl (hooks/SWAMP_Uploader/uploadConf.conf) This can only be specified if you are running the command from the command line (with --config-file). It cannot be specified elsewhere.

credentials-file

The location of the credentials file for the hook. If not specified, the default is in the same directory as uploadPackage.pl (hooks/SWAMP_Uploader/uploadCredentials.conf) This can only be specified if you are running the command from the command line (with --credentials-file). It cannot be specified in the configuration file.

log-file

The output location of the log file If not specified, the default is in the same directory as uploadPackage.pl (hooks/SWAMP_Uploader/logFile.txt) This is set by the installer and does not need to be modified.

cli_jar

The location of the java-cli jar from the git repository This will be specified by the installer, and should not need to be modified.

package-conf

The location of the package.conf file from the repository. If not specified, the default is ./package.conf

temp-dir

The location to store any temporary files needed for uploading the package. These will be deleted after the process is over. If not specified, the default is in the same directory as uploadPackage.pl (hooks/SWAMP_Uploader/.tempdir/)

Miscellaneous Options

help (-h)

Displays a help message detailing how to use the program and what options are available, then exits

print-platforms

Prints out all available platforms and then exits. Requires credentials to be entered.

print-projects

Prints out all available projects and then exits. Requires credentials to be entered.

print-tools

Prints out all available tools and then exits. Requires credentials to be entered.

verbose

Displays additional output to the console for updates on the program’s progress.

version (-v)

Displays the version of the currently installed program, then exits

4.2. In .git/hooks/SWAMP_Uploader/uploaderCredentials.conf

Parameter Description

username

Enter the username to your SWAMP account

password

Enter the password to your SWAMP account

Once you have these configurations in place, you can verify them with:

./.git/hooks/SWAMP_Uploader/uploadPackage.pl --verify

The program will verify your package is valid for submission without submitting anything to the SWAMP.

4.3. The package.conf File

Package.conf is a file which explains to the SWAMP how to build the the software so it can be assessed. It contains information similar to that you enter through the SWAMP GUI.

The current 'package.conf' file MUST be checked into the git workspace for an assessment to be run correctly by the swamp-scms-plugin. The last checked in version will be used for an assessment run.

There must be a package.conf file inside your git repository, location specified by the configuration file.
This file contains details on how the SWAMP should handle your package.
The format of each item is as follows:
package-short-name=test
Here is a full list of the valid options for configuration:

Parameter Description

package-short-name

name of package

package-version

version string of package

package-dir

directory of package from repository

package-classpath

Java classpath to for bytecode assessments

package-auxclasspath

Java auxclasspath to for bytecode assessments

package-srcdir

Location of Java source code for bytecode assessments

package-language

COMPUTER LANGUAGE used to write pkg, separate by spaces

build-sys

type of build system (see below)

config-dir

Directory to run the config-command in relative to package-dir directory

config-cmd

Command to configure the package (derived from <build-sys> if not present)

config-opt

Configuration Options

build-dir

Relative directory from <dir> to change to before building, default '.'

build-file

Relative path from <build-dir> to the build file

build-cmd

Command to build the package (default derived from <build-sys>)

build-opt

Build Option

build-target

Build target

android-sdk-target

Android Target String

package-language

To examine the current set of languages supported by the plugin or the SWAMP, run the plugin with --print-languages:

./.git/hooks/SWAMP_Uploader/uploadPackage.pl --print-languages

For example:

C
C++
HTML
Java
JavaScript
PHP
Python
Python-2
Python-3
Ruby
build-sys

To examine the current set of build systems supported by the plugin or the SWAMP, run the plugin with --print-build-sys:

./.git/hooks/SWAMP_Uploader/uploadPackage.pl --print-build-sys

For example:

android+ant
android+ant+ivy
android+gradle
android+maven
ant
ant+ivy
cmake+make
configure+make
gradle
java-bytecode
make
maven
no-build
none
other
python-distutils

5. Using the SWAMP Hook

Depending on how you configured the plugin, the package will be automatically uploaded and assessed to the SWAMP after every commit or push.

Login to the SWAMP you are using to view the status of the assessments and to view or download the results.

6. Updating the SWAMP Hook

To update the hook’s components to a newer version, you will need to update the software base that the hook was installed from.

You can do this either with 'git pull origin' on a checked out swamp-scms-plugin workspace, or by downloading a new archive from github.

Once a new version of the hook as been installed, you will need to visit each git workspace that uses the hook, and update the hook components in that workspace

For example, to update the hook in a git workspace cd my-git-workspace /path-to/swamp-scms-plugin/bin/installer.pl --git --update . ## review .instnew files for changes you may want to incorporate less .git/hooks/SWAMP_Uploader/uploadConfig.conf.instnew

If you would like to start over from scratch, you can do a force install. This will erase existing plugin configuration files and your git hook itself. Please backup those files before doing this operation.

cd my-git-workspace
backup_dir=.backup	## for example
mkdir -p $backup_dir
cp .git/hooks/post-receive $backup_dir
cp .git/hooks/post-commit $backup_dir
cp .git/hooks/SWAMP_Uploader/uploadConfig.conf $backup_dir
cp .git/hooks/SWAMP_Uploader/uploadCredentials.conf $backup_dir
/path-to/swamp-scms-plugin/bin/installer.pl --git --force .

After this, modify the upgraded configuration files and hooks from the backup copies.

## Setup configuration
your-editor .git/hooks/SWAMP_Uploader/uploadConfig.conf
## Setup SWAMP credentials
your-editor .git/hooks/SWAMP_Uploader/uploadCredentials.conf

7. Viewing the Results

The SWAMP web site can be used to view results of your assessments:

  1. Login to the SWAMP as normal.

  2. Click Results

  3. Click the checkbox next to the assessment results you would like to review

  4. Click View Assessment Results button