A GitHub Action to launch a workflow using Nextflow Tower - https://tower.nf.
This action uses the Nextflow Tower CLI.
This runs the current GitHub repository pieline on Nextflow Tower at the current commit hash when pushed to the dev
branch. The workflow runs on the user's personal workspace.
on:
push:
branches: [dev]
jobs:
run-tower:
runs-on: ubuntu-latest
steps:
- uses: nf-core/tower-action@v2
# Use repository secrets for sensitive fields
with:
access_token: ${{ secrets.TOWER_ACCESS_TOKEN }}
- uses: actions/upload-artifact@v3
with:
name: Tower debug log file
path: tower_action_*.log
This example never runs automatically, but creates a button under the GitHub repository Actions tab that can be used to manually trigger the workflow.
It runs on a specified installation of Tower, with a specific organisation workspace. It also calls an external pipeline to be run at a pinned version tag.
The --outdir
parameter is used to save results to a separate directory in the AWS bucket and the pipeline uses two config profiles.
name: Launch on Tower
# Manually trigger the action with a button in GitHub
# Alternatively, trigger on release / push etc.
on:
workflow_dispatch:
jobs:
run-tower:
name: Launch on Nextflow Tower
# Don't try to run on forked repos
if: github.repository == 'YOUR_USERNAME/REPO'
runs-on: ubuntu-latest
steps:
- uses: nf-core/tower-action@v2
# Use repository secrets for sensitive fields
with:
workspace_id: ${{ secrets.TOWER_WORKSPACE_ID }}
access_token: ${{ secrets.TOWER_ACCESS_TOKEN }}
api_endpoint: ${{ secrets.TOWER_API_ENDPOINT }}
compute_env: ${{ secrets.TOWER_COMPUTE_ENV }}
pipeline: YOUR_USERNAME/REPO
revision: v1.2.1
workdir: ${{ secrets.AWS_S3_BUCKET }}/work/${{ github.sha }}
# Set any custom pipeline params here - JSON object as a string
parameters: |
{
"outdir": "${{ secrets.AWS_S3_BUCKET }}/results/${{ github.sha }}"
}
# List of pipeline config profiles to use - comma separated list as a string
profiles: test,aws_tower
- uses: actions/upload-artifact@v3
with:
name: Tower debug log file
path: tower_action_*.log
Please note that a number of these inputs are sensitive and should be kept secure. We recommend saving them as appropriate using GitHub repository encrypted secrets. They can then be accessed with ${{ secrets.SECRET_NAME }}
in your GitHub actions workflow.
Note that if you are using secrets, these will be screened in the GitHub Actions log and appear as ***
.
[Required] Nextflow Tower personal access token.
Visit https://tower.nf/tokens to generate a new access token.
See the Nextflow Tower documentation for more details:
[Optional] Nextflow Tower workspace ID.
Nextflow Tower organisations can have multiple Workspaces. Use this field to choose a specific workspace.
Default: Your personal user's workspace.
Your Workspace ID can be found in the organisation's Workspaces tab:
Default: Your primary workspace.
[Optional] Nextflow Tower compute environment name (not ID).
Default: Your primary compute environment.
[Optional] Nextflow Tower API URL endpoint.
Default: api.tower.nf
[Optional] Workspace pipeline name or full pipeline URL.
For example, https://github.com/nf-core/sarek
.
Can also be the name of a preconfigured pipeline in Nextflow Tower.
Default: The current GitHub repository (https://github.com/${{github.repository}}
).
[Optional] Pipeline revision.
A pipeline release tag, branch or commit hash.
Default: The current GitHub commit hash (github.sha
).
[Required] Nextflow work directory.
The location that temporary working files should be stored. Must be accessible in the Nextflow Tower compute environment used.
[Optional] Pipeline parameters.
Additional pipeline parameters.
These should be supplied as a valid JSON object, quoted as a string in your GitHub Actions workflow. See example usage above for an example.
JSON is required (not YAML) because we do some parsing and dumping to ensure that the action handles multi-line string formatting correctly.
[Optional] Nextflow config profiles.
Pipeline config profiles to use. Should be comma separated without spaces.
[Optional] Nextflow config options.
Useful to pass custom Nextflow config options to the tw launch
command e.g.
jobs:
run-tower:
steps:
- uses: nf-core/tower-action@v2
with:
nextflow_config: |
process.errorStrategy = 'retry'
process.maxRetries = 3
# Truncated..
[Optional] Pre-run script before launch.
Pre-run script executed before pipeline launch. This would be particularly useful if you wanted to use a different version of Nextflow than the default available in Tower. You can set this in the pipeline Github Actions:
jobs:
run-tower:
steps:
- uses: nf-core/tower-action@v2
with:
pre_run_script: 'export NXF_VER=21.10.3'
# Truncated..
The action prints normal stdout info-level log messages to the actions console. However, it saves a verbose log file to tower_action_*.log
(the *
is a timestamp). We recommend using actions/upload-artifact
in your GitHub Actions workflow as shown in the examples above, this will then expose this file as a download through the workflow summary page.
This GitHub Action was written by Phil Ewels (@ewels), with help from and based on earlier work by Gisela Gabernet (@ggabernet).
If you use nf-core/tower-action
in your work, please cite the nf-core
publication as follows:
The nf-core framework for community-curated bioinformatics pipelines.
Philip Ewels, Alexander Peltzer, Sven Fillinger, Harshil Patel, Johannes Alneberg, Andreas Wilm, Maxime Ulysse Garcia, Paolo Di Tommaso & Sven Nahnsen.
Nat Biotechnol. 2020 Feb 13. doi: 10.1038/s41587-020-0439-x.