How to update a Dockstore workflow

Leyla Tarhan
  • Updated

Once you've created a workflow and imported it into Terra, your analyses might continue to evolve. This article describes how to edit a workflow that's sourced from Dockstore so that you're running the most up-to-date version on Terra.

Step 1: Find your workflow's GitHub repository

You can navigate to the correct GitHub repository in three ways: from Terra, from Dockstore, and directly from GitHub.

  • 1.1. If you've already imported an earlier version of the workflow into your Terra workspace, open the workflow from the workspace's Workflows tab. 

    1.2. Click on the Source link in the workflow's configuration menu. This will take you to the Dockstore page for the workflow.

    Screenshot of the workflow configuration page for an example workflow on Terra. An orange rectangle highlights the Source link, which is just below the Version drop-down menu.

    1.3. From the Dockstore page, click on the workflow's Info tab and then click on the Source code link under the Workflow Information section. This will take you to the workflow's GitHub repository.

    Screenshot of the Dockstore page for an example workflow. An orange rectangle highlights the Source Code link, which is the first item under the Workflow Information section in the Info tab.

  • 1.1. Go directly to dockstore.org

    1.2. Log in and click on My Dockstore.

    Screenshot of the Dockstore homepage. An orange rectangle highlights the My Dockstore button with a speedometer icon at the top right of the page.

    1.3. Select Workflows from the left-hand panel of the My Dockstore dashboard.

    1.4. Choose your workflow.

    1.5. Click on the workflow's Info tab and then click on the Source code link under the Workflow Information section. This will take you to the workflow's GitHub repository.

    Screenshot showing an example My Dockstore screen on the Dockstore website. Orange rectangles highlight (1) the Workflows button on the left-hand panel, (2) an individual workflow, and (3) the Source Code link for that workflow. Click (1) and (2) in order to see (3).

  • 1.1. Go directly to github.com.

    1.2. Log in and navigate to your repositories.

    1.3. Select the repository used for this workflow.

Step 2: Edit the workflow

2.1. Update your workflow by editing the files in the workflow's GitHub repository.

2.2. Push the changes to GitHub. Be sure to push the changes to a branch that already has a .dockstore.yml file (or create a new .dockstore.yml file on the branch that you push to, following the instructions in How to set up a WDL on GitHub/Dockstore).

Step 3 (optional): Save a new version of your workflow

In some cases, your workflow edits may be small and you wouldn't want to return to an earlier version of the workflow. In other cases, your edits might be more significant - for example, you might update the workflow to call a different package or batch-correction algorithm.

When making significant changes, it's often useful to save your changes as a discrete version. You'll be able to choose between versions when running the workflow on Terra. This way, you can compare results from different versions or quickly revert to an earlier version if you discover that it's a better analysis.

To save your changes as a new workflow version, simply create a new branch in your GitHub repository when pushing the changes to GitHub:

3.1. After updating your workflow's WDL file(s), commit your changes to the repository (on the GitHub online interface, click the Commit Changes button).

3.2. When making the commit, select the option to create a new branch, rather than committing directly to the current branch.

3.3. Provide a name for the new branch.

3.4. Click Propose changes.

Screenshot showing the window that appears on Github after editing a file and clicking the Commit Changes button. Orange rectangles highlight the options that will create a new branch in the repository, in order to create a distinct version of your workflow. Select 'Create a new branch for this commit and start a pull request' and provide a name for the branch (version), then click Propose Changes.

3.5. Create a new version of the .dockstore.yml file, save it to this new branch, and commit your changes. If you don't include a .dockstore.yml file in the new branch, Dockstore won't sync your changes.

Make sure that your .dockstore.yml file points to the correct file Double-check that your .yml file uses the correct name and path for your updated WDL file. See an example file in How to set up a WDL on Github/Dockstore.

What to expect

How are these changes passed along to Terra? The process is different depending upon whether you've registered this workflow to Dockstore using the GitHub App (which we recommend). This topic is covered in How to set up a WDL on GitHub/Dockstore and Dockstore's documentation.

  • If you've registered the workflow to Dockstore using the GitHub App, the changes should sync automatically to Dockstore, and the updated version should appear on Terra within a few minutes once you've pushed your changes to GitHub.
  • If you didn't use the GitHub App, the changes won't sync automatically to Dockstore. Instead you'll have to manually refresh the workflow on Dockstore after pushing your changes to GitHub. Once you've done this, the updated version should appear on Terra within a few minutes.
  • If you've created a new branch to save a distinct version of your workflow, you'll see that new version show up on the Terra workflow under the Version menu in the workflow's configuration menu.

Screenshot showing the configuration menu for an example workflow on Terra. An orange rectangle highlights the Version menu, which is used to select the workflow's version.

Additional Resources

 

 

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.