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.
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 files, 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.
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.
- 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.