Register a Tool on Dockstore
Tutorial Goals
Discover how to register a tool on Dockstore
Publish your tool
Assumptions
This document assumes you have already have a tool ready to register. You do not need to have a Dockerfile associated with it unless you are using one our legacy registration methods (more on that below).
If you followed Getting Started With CWL to create a CWL tool, you will now have your Dockerfile
and Dockstore.cwl
in GitHub, have setup Quay.io to automatically build your Docker image, and have linked your accounts to Dockstore. This will allow you to use any of our registration methods, including legacy methods. Of course, you can always follow along with your own unique tools too, which may or may not be associated with an autobuilding Docker image.
Regardless of how you made your tool, this tutorial will assume you are using CWL. For all other languages, please see our documentation on workflows instead.
Note
The WDL community does not explicitly differentiate tools versus workflows. However, Dockstore allows the registration of “WDL tools” using legacy registration methods. 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.
There are a variety of ways to get your tools into Dockstore. Users can either use GitHub App registration or our legacy registration methods. GitHub App registration is the recommended way to register all new tools on Dockstore. GitHub App tools and tools registered using our other methods (legacy tools) are very different from one another. Use the following questions to determine which method to use:
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
If you must use the legacy tool registration methods, then you may want to read Dockstore Tools Overhaul before continuing to the legacy methods described below.
Register Your Tool to Automatically Sync with GitHub (Recommended)
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.
Dockstore has added GitHub App support for registering tools. Using GitHub Apps, Dockstore can react to changes on GitHub as they are made, keeping Dockstore synced with GitHub automatically. You can read more about it in our docs about the Dockstore GitHub App, but a summary is present below.
Installing the GitHub App is simple. Navigate to /my-tools
, /my-workflows
, or /my-services
using the drop down menu in the top right. In these screenshots, we will go via /my-tools
, but the process is essentially the same for any of the other options.

Click the +
button on the left hand sidebar.

A window will appear asking how you would like to register your tool, workflow, or service. Select Register using GitHub Apps
.

Click + Manage Dockstore Installation on GitHub
. You’ll then be redirected to GitHub where you can select which repositories can be accessed by the GitHub app.

You’ll then be redirected to GitHub where you can grant the app access to specific repositories within whatever organization you are installing into. Note that GitHub treats your username as its own “organization.” For instance, my GitHub username is aofarrel. If I want to install the GitHub App so it could access aofarrel/mycoolrepo, I would choose the first option here.

Install our GitHub App on either all repositories in an organization or on specific repositories
After selection of an organization, you can select whether to give access to all repositories or only select ones. If the organization you choose is intended to be just for Dockstore tools/workflows/services, you may want to allow access to all repositories. Otherwise, it is may be more intuitive to select only certain repositories. Click save and you will be taken back to the page you started on in Dockstore – either /my-tools
, /my-workflows
, or /my-services
, depending where you started.
Important
The GitHub user who first adds a workflow onto Dockstore must correspond to a user on Dockstore.
You should now see the organization and the repositories you chose to keep track of in the “unpublished” tab. Here’s an example involving /my-services
:

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
Automatic Syncing with GitHub Apps and .dockstore.yml - details on writing a .dockstore.yml file
Migrating Your Existing Workflows - a tutorial on converting already registered workflows
Troubleshooting and FAQ - tips on resolving Dockstore Github App issues.
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 you’ve installed our GitHub app on a repository or organization, you’ll 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 created (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 to show you how easy it is to use. 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 DockstoreThe 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
The following methods are NOT recommended and should only be used if your tool descriptor files are registered on BitBucket or GitLab.
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.
Find Other Tools
You can find tools on the Dockstore website or also through the
dockstore tool search
command line option.
Next Steps
You can follow this basic pattern for each of your Docker-based tools. 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.