githubrelease

此项目旨在简化在GitHub上分发发行版的过程。

我制作它是因为从服务器下载文件，然后从桌面上传到GitHub，感觉很不方便。

从GitHub下载文件到桌面，然后通过SCP传输到服务器，也很不方便。

这个工具在SSH会话中工作得很好。

-- @j0057于2014年8月13日星期三

示例

从命令行

# create a prerelease
$ githubrelease release jcfr/sandbox create 1.0.0 --prerelease

# upload assets
$ githubrelease asset jcfr/sandbox upload 1.0.0 "dist/*"

# publish the release
$ githubrelease release jcfr/sandbox publish 1.0.0

# or all together: create with custom name, upload assets, and publish
$ githubrelease release jcfr/sandbox create 2.0.0 --publish --name "Awesome 2.0" "dist/*"

...或者甚至从Python中

from github_release import gh_release_create
gh_release_create("jcfr/sandbox ", "2.0.0", publish=True, name="Awesome 2.0", asset_pattern="dist/*")

也就是说，如果您正在寻找完整的GitHub API Python支持，您可能需要查看像github3py或PyGithub这样的项目。

目录

• githubrelease
• 示例
• 功能
• 安装
• 配置
• 使用CLI
  • 发行命令
  • 资产命令
  • 引用命令
• 使用模块
• 测试
• 维护者：如何创建发行版？
• 许可证

功能

• 创建发行版、预发行版或草稿发行版
• 更新任何发行版元数据，包括引用的提交
• 支持通配符表达式（或通配符表达式列表）
  • 用于上传或下载资产
  • 用于选择性删除资产
• 报告下载和上传进度
• 允许从发布中删除单个资产
• 服务器失败时重试上传
• 优雅地处理包含无效资产的发布（状态为新的资产）
• 通过GITHUB_TOKEN环境变量或~/.netrc文件进行身份验证
• 纯Python编写，仅依赖于requests和click

安装

已发布的稳定版本可以从pypi安装

pip install githubrelease

使用以下方法安装最新版本

pip intall githubrelease -f https://github.com/j0057/github-release/releases/tag/latest

配置

首先，生成一个新令牌。它至少应该有repo权限。

然后，有三种选项

• 设置GITHUB_TOKEN环境变量

export GITHUB_TOKEN=YOUR_TOKEN
/path/to/command

• 传递--github-token CLI参数。例如

$ githubrelease --github-token YOUR_TOKEN release jcfr/sandbox create --prerelease 1.0.0

• 将密钥放入~/.netrc，该文件应具有模式0600（-rw-------）

machine api.github.com
login YOUR_TOKEN
password x-oauth-basic

machine uploads.github.com
login YOUR_TOKEN
password x-oauth-basic

其中YOUR_TOKEN应替换为生成的令牌。

使用CLI

该软件包安装了一个名为githubrelease的CLI。

$ githubrelease 
Usage: githubrelease [OPTIONS] COMMAND [ARGS]...

  A CLI to easily manage GitHub releases, assets and references.

Options:
  --github-token TEXT         [default: GITHUB_TOKEN env. variable]
  --progress / --no-progress  Display progress bar (default: yes).
  --help                      Show this message and exit.

Commands:
  asset    Manage release assets (upload, download, ...)...
  ref      Manage references (list, create, delete, ...)...
  release  Manage releases (list, create, delete, ...)...

Run 'githubrelease COMMAND --help' for more information on a command.

为了向后兼容，它还安装了github-release和github-asset

release命令

此命令处理发布。一般用法是

githubrelease release username/reponame command [tag] [options]

它理解以下命令

可选参数

• create

  --name NAME
  --body BODY
  --publish
  --prerelease
  --target-commitish TARGET_COMMITISH
  --help
  [ASSET_PATTERN]...

• edit

  --tag-name TAG_NAME
  --target-commitish TARGET_COMMITISH
  --name NAME
  --body BODY
  --draft/--publish
  --prerelease/--release
  --dry-run
  --verbose
  --help

• delete

  --keep-pattern KEEP_PATTERN
  --type [all, draft, prerelease, release]
  --older-than HOURS
  --dry-run
  --verbose
  --help
  [ASSET_PATTERN]...

asset命令

此命令处理发布资产。一般用法是

githubrelease asset username/reponame command [tag] [filename] [options]

它理解以下命令

可选参数

• delete

--keep-pattern KEEP_PATTERN

备注

在指定文件名时，支持类似shell的通配符，但请确保使用单引号引用，即不要让shell展开通配符模式。

对于download命令，您还需要指定一个'*'的tagname

示例

# upload all example-project-1.4* files in /home/me/pkg
$ githubrelease asset octocat/example-project upload 1.4 '/home/me/pkg/example-project-1.4*'

# download all wheels from all releases
$ githubrelease asset octocat/example-project download '*' '*.whl'

# download all files from release 1.4
$ githubrelease asset octocat/example-project download 1.4

# download all files from example-project
$ githubrelease asset octocat/example-project download

ref命令

此命令处理git引用。一般用法是

githubrelease ref username/reponame command [options]

它理解以下命令

使用模块

Python API反映了命令行界面。大多数可用函数名遵循以下模式

gh_<COMMAND>_<COMMAND>

其中第一个<COMMAND>是release、asset或ref，第二个是上述文档中分别记录的任何命令。

每个函数接受的参数也反映了命令行界面。通常的签名是

gh_<COMMAND>_<COMMAND>(repo_name, [param, [param,]] [option, [option]])

例如，以下是gh_release_create的签名

def gh_release_create(repo_name, tag_name, 
                      name=None, publish=False, prerelease=False, target_commitish=None):

每个参数或选项的类型通常可以从其名称中推断出来。如果不能，请考虑查看github_release.py。

repo_name        -> str
tag_name         -> str
name             -> str
publish          -> bool
prerelease       -> bool
target_commitish -> str

测试

在TravisCI上自动运行测试

• 编码风格检查
• 集成测试

由于集成测试期望设置 GITHUB_TOKEN，因此在提交来自分叉的拉取请求时将 不会 执行。实际上，测试需要设置 GITHUB_TOKEN 以重置和更新 github-release-bot/github-release-test-py2 和 github-release-bot/github-release-test-py3。

为了在本地执行集成测试，并确保您的出色贡献按预期工作，您需要

• 创建一个包含至少一个提交的测试仓库（例如 yourname/github-release-test）
• 设置环境变量 INTEGRATION_TEST_REPO_NAME=yourname/github-release-test
• 执行 python setup.py test

要执行特定测试，以下命令也有效

export GITHUB_TOKEN=YOUR_TOKEN
export INTEGRATION_TEST_REPO_NAME=yourname/github-release-test
$ pytest tests/test_integration_release_create.py::test_create_release

接下来，计划将利用像 betamax 这样的工具，允许拦截每个请求并尝试找到已经拦截并记录的匹配请求。

维护者：如何创建发行版？

1. 按照此处所述配置 ~/.pypirc。

2. 确保cli和模块按预期工作。

3. 选择下一个发布版本号

   release="X.Y.Z"
   

4. 审查 CHANGES.md，将 Next Release 替换为 X.Y.Z，提交并推送。考虑在提交信息中使用 [ci skip]。

   sed -i -e "s/Next Release/${release}/" CHANGES.md
   sed -i -e "s/============/=====/" CHANGES.md
   git add CHANGES.md
   git commit -m "CHANGES.md: Replace \"Next Release\" with \"${release}\"
   
   [ci skip]
   "
   

   审查提交，然后推送

   git push origin master
   

5. 标记发布版本。需要带有签名的GPG密钥

   git tag -s -m "githubrelease ${release}" ${release} origin/master
   

   然后推送

   git push origin ${release}
   

6. 创建源tar包和二进制wheel

   rm -rf dist/
   python setup.py sdist bdist_wheel
   

7. 将包上传到测试PyPI实例

   twine upload --sign -r pypitest dist/*
   

8. 检查PyPI测试包页面。

9. 将包上传到PyPI实例：

   twine upload --sign dist/*
   

10. 检查PyPI包页面。

11. 创建虚拟环境，并确保可以安装包

    mkvirtualenv test-githubrelease-install
    pip install githubrelease
    

12. 创建github发布并上传包

    export GITHUB_TOKEN=YOUR_TOKEN
    githubrelease release j0057/github-release create ${release} --name ${release} --publish ./dist/*
    

13. 通过从CHANGES.md复制相关内容来更新发布说明

    export EDITOR=vim
    githubrelease release j0057/github-release release-notes ${release}
    

14. 清理

    deactivate
    rmvirtualenv test-githubrelease-install
    

    然后更新 CHANGES.md

    sed -i '1i Next Release\n============\n' CHANGES.md
    git add CHANGES.md
    git commit -m "Begin ${release} development
    
    * CHANGES.md: Add \"Next Release\" section
    
    [ci skip]
    "
    git push origin master
    

常见问题解答

• 为什么我得到错误 requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url https://api.github.com/repos/...？

  这很可能意味着您指定的GitHub令牌无效。

许可证

由 Joost Molenaar (@j0057) 和 Jean-Christophe Fillion-Robin (@jcfr) 撰写

此内容受Apache License，版本2.0保护

https://apache.ac.cn/licenses/LICENSE-2.0

许可证文件于2017年2月12日修订版本0393859时添加，但您可能认为许可证也适用于所有以前的版本。