gh-trs: 使用 GitHub 发布和测试您自己的 GA4GH TRS API 的 CLI 工具

CLI 工具，用于将工作流程作为 GA4GH 工具注册服务 (TRS) API 发布，并使用 GitHub 测试工作流程。

功能特点

• 从工作流程文档的 URL（称为 config_file）生成发布模板
• 根据 gh-trs 配置文件测试工作流程
• 将工作流程作为 GA4GH TRS API 发布到 GitHub

注意，存在 ddbj/yevis-cli 作为更全面且维护得更好的工具。基本上，我推荐使用它。

安装

使用无任何依赖项构建的单个二进制文件

$ curl -fsSL -O https://github.com/suecharo/gh-trs/releases/latest/download/gh-trs
$ chmod +x ./gh-trs
$ ./gh-trs --help

或者，使用 Docker 环境（也支持 docker-compose）

$ docker-compose up -d --build
$ docker-compose exec app gh-trs --help

入门

首先，gh-trs 需要通过 GitHub REST API 进行各种操作，需要 GitHub 个人访问令牌。请参阅 GitHub 文档 - 创建个人访问令牌 了解如何生成 GitHub 个人访问令牌。

所需的作用域如下（也请参见截图）

• repo-public_repo
• user-read:user

生成 GitHub 个人访问令牌 后，您需要通过以下方式之一将其传递给 gh-trs

• 环境文件：将令牌写入 .env 文件，如 GITHUB_TOKEN=<paste_your_token>
• 环境变量：设置 GITHUB_TOKEN 环境变量
• 命令行选项：使用 --gh-token <paste_your_token> 选项

使用工作流程 trimming_and_qc.cwl 作为示例。

首先，从工作流程文档的 GitHub 位置生成 gh-trs 配置文件的模板

$ gh-trs make-template https://github.com/suecharo/gh-trs/blob/main/tests/CWL/wf/trimming_and_qc.cwl

test_config_CWL_template.yml 是将要生成内容的示例。

接下来，编辑生成的 ./gh-trs-config.yml，如 test_config_CWL.yml。

主要编辑部分如下

• workflow.files：要包含在工作流程中的文件列表
• workflow.testing：要运行的测试列表

更多详细信息，请参阅 readme - validate。

然后，根据 gh-trs 配置文件生成 GA4GH TRS API，并将其部署在 GitHub Pages 上。

$ gh-trs publish --repo <repo_owner>/<repo_name> ./gh-trs-config.yml

已部署的工作流程可以从 GA4GH TRS API 规范 中检索。

$ curl -L https://<repo_owner>.github.io/<repo_name>/tools

使用方法

本节描述了 gh-trs 的某些子命令。

$ gh-trs --help
gh-trs 0.1.1
CLI tool to publish and test your own GA4GH TRS API using GitHub

USAGE:
    gh-trs <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    help             Prints this message or the help of the given subcommand(s)
    make-template    Make a template for the gh-trs configuration file
    publish          Publish the TRS response to GitHub
    test             Test the workflow based on the gh-trs configuration file
    validate         Validate the gh-trs configuration file

make-template

从主要工作流程文件的 GitHub 位置生成 gh-trs 配置文件模板。

$ gh-trs make-template --help
gh-trs-make-template 0.1.1
Make a template for the gh-trs configuration file

USAGE:
    gh-trs make-template [FLAGS] [OPTIONS] <workflow-location>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Verbose mode

OPTIONS:
        --gh-token <github-token>    GitHub Personal Access Token
    -o, --output <output>            Path to the output file [default: gh-trs-config.yml]

ARGS:
    <workflow-location>    Location of the primary workflow document

仅接受托管在 GitHub 上的 URL 作为 workflow-location。这是一个类似于 https://github.com/suecharo/gh-trs/blob/main/tests/CWL/wf/trimming_and_qc.cwl 的 URL，稍后将转换为类似 https://raw.githubusercontent.com/suecharo/gh-trs/645a193826bdb3f0731421d4ff1468d0736b4a06/tests/CWL/wf/trimming_and_qc.cwl 的 raw URL。

gh-trs 收集各种信息并生成 gh-trs 配置文件模板。特别是，workflow.files 会从主要工作流程位置递归生成文件列表。

validate

验证 gh-trs 配置文件的架构和内容。

$ gh-trs validate --help
gh-trs-validate 0.1.1
Validate the gh-trs configuration file

USAGE:
    gh-trs validate [FLAGS] [OPTIONS] [config-locations]...

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Verbose mode

OPTIONS:
        --gh-token <github-token>    GitHub Personal Access Token

ARGS:
    <config-locations>...    Location of the gh-trs configuration files (local file path or remote URL) [default:
                             gh-trs-config.yml]

以下是 gh-trs 配置文件中某些字段的验证规则解释

• id：工作流程的 ID。由 make-template 命令生成。如果您想更新现有工作流程，请填写现有工作流程的 ID。
• version：版本形式为 x.y.z。
• authors：作者列表。
• workflow.name：请自由填写。允许的字符包括 a-z、A-Z、0-9、~!@#$%^&*()_+-={}[]|:;,.<>?，以及空格。
• workflow.readme：用于 describe 工作流程的字段。使用您喜欢的任何 URL。
• workflow.language：支持 CWL、WDL、NFL 和 SMK。
• workflow.files：文件列表。指定为 type: secondary 的文件将在工作流程执行时，以 target 作为路径放置在执行目录中。
• workflow.testing：测试列表。有关编写测试的详细信息，请参阅 test。

$ gh-trs test --help
gh-trs-test 0.1.1
Test the workflow based on the gh-trs configuration file

USAGE:
    gh-trs test [FLAGS] [OPTIONS] [config-locations]...

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information
    -v, --verbose    Verbose mode

OPTIONS:
    -d, --docker-host <docker-host>      Location of the docker host [default: unix:///var/run/docker.sock]
        --gh-token <github-token>        GitHub Personal Access Token
    -w, --wes-location <wes-location>    Location of WES in which to run the test. If not specified, `sapporo-service`
                                         will be started

ARGS:
    <config-locations>...    Location of the gh-trs configuration files (local file path or remote URL) [default:
                             gh-trs-config.yml]

testing:
  - id: test_1
    files:
      - url: "https://example.com/path/to/wf_params.json"
        target: wf_params.json
        type: wf_params
      - url: "https://example.com/path/to/wf_engine_params.json"
        target: wf_engine_params.json
        type: wf_engine_params
      - url: "https://example.com/path/to/data.fq"
        target: data.fq
        type: other

$ gh-trs publish --help
gh-trs-publish 0.1.1
Publish the TRS response to GitHub

USAGE:
    gh-trs publish [FLAGS] [OPTIONS] --repo <repo> [config-locations]...

FLAGS:
        --from-trs     Recursively get the gh-trs configuration files from the TRS endpoint and publish them. It is
                       mainly intended to be tested and published all at once in a CI environment. If you use this option,
                       specify the TRS endpoint for `config_location`
    -h, --help         Prints help information
    -V, --version      Prints version information
    -v, --verbose      Verbose mode
        --with-test    Test before publishing

OPTIONS:
    -b, --branch <branch>                GitHub branch to publish to [default: gh-pages]
    -d, --docker-host <docker-host>      Location of the docker host [default: unix:///var/run/docker.sock]
        --gh-token <github-token>        GitHub Personal Access Token
    -r, --repo <repo>                    GitHub Repository to publish to. (e.g. owner/name)
    -w, --wes-location <wes-location>    Location of WES in which to run the test. If not specified, `sapporo-service`
                                         will be started

ARGS:
    <config-locations>...    Location of the gh-trs configuration files (local file path or remote URL) [default:
                             gh-trs-config.yml]

$ gh-trs publish --repo <owner/name> --branch gh-pages --with-test --from-trs https://example.com/path/to/trs

jobs:
  test-and-publish:
    steps:
      - name: gh-trs-action
        uses: suecharo/gh-trs-action@v1
        with:
          gh-token: ${{ secrets.GITHUB_TOKEN }}
          repo: suecharo/gh-trs
          branch: gh-pages
          trs-endpoint: https://suecharo.github.io/gh-trs/

$ gh-trs publish --verbose --with-test --repo ${{ inputs.repo }} --branch ${{ inputs.branch }} --from-trs ${{ inputs.trs-endpoint }}

name: page-build-ci

on:
  page_build: {}

jobs:
  test-and-publish:
    runs-on: ubuntu-latest
    if: "! contains(github.event.head_commit.message, 'in CI')"
    steps:
      - name: gh-trs-action
        uses: suecharo/gh-trs-action@v1
        with:
          gh-token: ${{ secrets.GITHUB_TOKEN }}

$ gh-trs publish --repo suecharo/gh-trs ./tests/test_config_CWL.yml

name: schedule-ci

on:
  schedule:
    - cron: "0 0 * * 0" // every Sunday at midnight

jobs:
  test-and-publish:
    runs-on: ubuntu-latest
    steps:
      - name: gh-trs-action
        uses: suecharo/gh-trs-action@v1
        with:
          gh-token: ${{ secrets.GITHUB_TOKEN }}