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.
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.
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
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.
| Parameter | Description |
|---|---|
Assessment Options |
|
platform (-p) |
The name of the platforms used in the assessment
For a full list of platforms, run
|
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
|
tool (-t) |
The tool names used for the assessment
For a full list of tools, run
|
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 |
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 |
upload |
If you set |
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 |
| 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 --verifyThe program will verify your package is valid for submission without submitting anything to the SWAMP.
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 |
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
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
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.
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