Publishing to the Tool Shed

The Galaxy Tool Shed (referred to colloquially in Planemo as the “shed”) can store Galaxy tools, dependency definitions, and workflows among other Galaxy artifacts. This guide will assume some basic familiarity with the shed - please review the Tool Shed Wiki for an introduction.

Configuring a Shed Account

Before getting started, it is a good idea to have accounts on the Galaxy test and (optionally) main Tool Sheds. Also, if you haven’t initialized a global Planemo configuration file (~/.planemo.yml) this can be done with.

planemo config_init

This will populate a template ~/.planemo.yml file and provide locations to fill in shed credentials for the test and main Tool Sheds. For each shed, fill in either an API key or an email and password. Also specify the shed_username created when registering shed accounts. All these options can be specified and/or overridden on each planemo command invocation - but that becomes tedious quickly.

Creating a Repository

Planemo can be used to used to publish “repositories” to the Tool Shed. A single GitHub repository or locally managed directory of tools may correspond to any number of Tool Shed repositories. Planemo maps files to Tool Shed repositories using a special file called .shed.yml.

From a directory containing tools, a package definition. etc… the shed_init command can be used to bootstrap a new .shed.yml file.

planemo shed_init --name=<name>
                  --owner=<shed_username>
                  --description=<short description>
                  [--remote_repository_url=<URL to .shed.yml on github>]
                  [--homepage_url=<Homepage for tool.>]
                  [--long_description=<long description>]
                  [--category=<category name>]*

There is not a lot of magic happening here, this file could easily be created directly with a text editor - but the command has a --help to assist you and does some very basic validation.

Note

Periods and hyphens are disallowed in repository names, it is recommended replacing periods in the version number with underscores.

The following naming conventions are recommended and in some cases Planemo will determine the repository type based on adherence to these conventions (for packages and suites specifically).

Repository Type	Recommended Name	Examples
Data Managers	data_manager_$name	data_manager_bowtie2
Packages	package_$name_$version	package_aragorn_1_2_36
Tool Suites	suite_$name	suite_samtools
Tools	$name	stringtie, bedtools

More information on .shed.yml can be found as part of the IUC best practice documentation.

After reviewing .shed.yml, this configuration file and relevant shed artifacts can be quickly linted using the following command.

planemo shed_lint --tools

Once the details the .shed.yml are set and it is time to create the remote repository and upload artifacts to it - the following two commands can be used - the first only needs to be run once and creates the repository based the metadata in .shed.yml and the second uploads your actual artifacts to it.

planemo shed_create --shed_target testtoolshed

Updating a Repository

Ensure the Galaxy Test Tool Shed is enabled in Galaxy’s config/tool_sheds_conf.xml file and install and test the new repository.

If modifications are required these can be reviewed using the shed_diff command.

planemo shed_diff --shed_target testtoolshed

Note

If you look at tools-iuc you will see it is common practice to leave details such as shed target and changeset_revision from tool_dependencies.xml and repository_dependencies.xml files. These are required by the Tool Shed but it will populate them on upload and leaving them blank allows uploading the same artifacts to the Test and Main sheds. The upshot of this is however is that shed_diff will always print diffs on these artifacts.

Modified artifacts can be uploaded using the following command.

planemo shed_update --check_diff --shed_target testtoolshed

The --check_diff option here will ensure there are significant differnces before uploading new contents to the tool shed.

Once tools and required dependency files have been published to the tool shed, the actual shed dependencies can be automatically and installed and tool tests ran using the command:

planemo shed_test --shed_target testtoolshed

Once your artifacts are ready for publication to the main Tool Shed, the following commands to create a repository there and populate it with your repository contents.

planemo shed_create

Advanced Usage

The above usage is relatively straight forward - it will map the current directory to a single repository in the Tool Shed.

See Pull Request 143 and linked examples for details on more advanced options such as mapping each tool to its own repository automatically (a best practice) or building enitrely custom repository definitions manually.