Register a Tool on Dockstore

Tutorial Goals

  • Discover how to register a tool on Dockstore

  • Publish your tool

Assumptions

This document assumes you already have a tool ready to register.

If you followed Getting Started With CWL to create a CWL tool, you will now have a Dockstore.cwl in GitHub and have linked your accounts to Dockstore. This will allow you to use the Dockstore GitHub App to register your tool. Of course, you can always follow along with your own unique tools too. Regardless of how you made your tool, this tutorial will assume you are using CWL. For all other languages, you will want to register a workflow.

Note

Dockstore allows the registration of “WDL tools” using legacy registration methods. However, the WDL community does not explicitly differentiate tools versus workflows. We encourage people to register WDLs as workflows instead.

Register Your Tool in Dockstore

Note

You do not need an account to search for workflows on Dockstore or to launch them with our compute partners. However, to register content on Dockstore, you must have an account on Dockstore and link the necessary third-party accounts. Once this is done you can register workflows from the My Workflows page, tools from the My Tools page, or services from the My Services page.

We recommend users register their tool with our GitHub App to benefit from GitHub’s features and automatic syncing. If you do not wish to use GitHub, we do support other methods of registration in our legacy registration methods. Use the following questions to determine which registration method works for you:

  • Registering a CWL CommandLineTool?

    • Hosted on GitHub?

      • Register your tool to automatically sync using GitHub Apps

    • Hosted on BitBucket or GitLab?

      • Register using legacy tool registration methods or consider uploading your work to GitHub

  • Registering a CWL Workflow, WDL, Nextflow, or Galaxy descriptor files?

    • Hosted on GitHub?

      • Register your workflow to automatically sync using GitHub Apps

    • Hosted on BitBucket or GitLab?

      • Register using legacy workflow registration methods or consider uploading your work to GitHub

A note on permissions

If you are adding the GitHub App to an organization for which you are not an admin, GitHub may block your ability to install the app, even if you have maintainer access to the repository you are hoping to give the GitHub App permission to view. Please see this FAQ entry for more information.

See also

Ensuring sychronization

Once the GitHub App is installed and a .dockstore.yml is present, please make sure to push one additional commit to your repository. This helps make sure your workflows, tools, and services show up in Dockstore.

Once GitHub app is installed on a repository or organization, you will need to add a .dockstore.yml file to the root directory of a branch of the repository that contains your tool. This file contains information like tool path, test parameter file, tool name, etc. When a push is made or a tag is created on GitHub with a .dockstore.yml, Dockstore will add that branch to the corresponding tool on Dockstore. If the tool doesn’t already exist on Dockstore, one will be registered (but will not automatically be published publically). Note that a single .dockstore.yml file can describe multiple tools, if all of those tools are in the same repository.

Below is a simple example of a .dockstore.yml file for an alignment tool. Note that all file paths in the file must be absolute.

version: 1.2
tools:
   - subclass: CWL
     primaryDescriptorPath: /aligner.cwl
     testParameterFiles:
     - /test/aligner.cwl.json

If you had our GitHub App installed on the repository myorg/alignments and then add the above .dockstore.yml to the develop branch, the following would occur.

  • A CWL tool with the ID github.com/myorg/alignments will be created on Dockstore

  • The version develop is added to the tool github.com/myorg/alignments

  • The version has the primary descriptor file set to /aligner.cwl

  • The version has one test parameter file: /test/aligner.cwl.json

Now that your tool has been added, any time there is a push to a branch on GitHub for this repository that has a .dockstore.yml, it is automatically updated on Dockstore! Anytime there is a deletion of a branch on GitHub that has a .dockstore.yml, the version is removed from Dockstore.

For more information on this method, as well as general troubleshooting advice, please check our Dockstore GitHub Apps Overview page.

Legacy Tool Registration

Important

Workflows and tools added to Dockstore via our legacy registration methods do not automatically stay in sync with their source repository. Instead, someone with access to the entries on Dockstore must periodically log into Dockstore and press a button to trigger a refresh. Although this process is quick and will bring in all new tags, commits, and branches with the click of a button, it is easy to forget to do this and might not be appropriate for frequently-updated tools and workflows. For this reason, we recommend using GitHub App registration instead.

If you are using BitBucket or GitLab and would prefer not to use GitHub, or if you are using GitHub but do not wish to install our app, our legacy registration methods have you covered. Several options are available to you and described in our legacy registration methods documentation. If you must use the legacy tool registration methods, then you may want to read how our definition of tool is different for these legacy methods.

Sharing Your Tool

After you have successfully added your tool onto Dockstore and have it synced with GitHub, Bitbucket, or GitLab, or hosted directly in Dockstore, you are now ready to share your tool with the public! Assuming that your tool has at least one valid version, you can publish your tool for everyone to use. Simply select the tool on the /my-tool page and click publish.

Next Steps

Once registered, you can send links to your tools on Dockstore to colleagues and use it as a public platform for sharing your tools.

Learn about Workflows and how they differ from tools.