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.
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.
-
1.1. Go directly to dockstore.org.
1.2. Log in and click on My Dockstore.
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.
-
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.
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.
Additional Resources
- To learn how to find and import a workflow from the Broad Methods Repository, see Finding the workflow (method) you need (and its JSON) in the Methods Repository.
- To learn how to find and import a workflow from Dockstore, see How to import a workflow and its parameter file from Dockstore into Terra.
- To learn how to update a workflow sourced from the Broad Methods Repository and save it as a new version or snapshot, see Create, edit, and share a new workflow.
- To learn how to create a new workflow in Dockstore, see How to set up a WDL on GitHub/Dockstore.