用于管理Git镜像的工具。
项目描述
mirror-tool
用于维护Git subtree镜像的工具。
安装
从PyPI安装mirror-tool包。
pip install mirror-tool
或者，直接作为容器镜像运行mirror-tool。
注意，您必须将您想要管理的git仓库作为目录暴露给容器，作为当前工作目录，以及设置任何需要的环境变量（如果启用了GitLab功能）。如何操作的细节超出了本README的范围，但一个示例命令可能如下所示
podman run \
-v $PWD:/workdir:Z -w /workdir \
quay.io/rmcgover/mirror-tool:latest \
update-local
用法
mirror-tool有以下子命令。请安装该工具并使用--help运行以获取有关可用命令和选项的完整文档。
mirror-tool validate-config
验证当前目录中的.mirror-tool.yaml文件，或指定的配置文件是否有效。
如果找到有效的配置文件，则退出代码为0。
mirror-tool update-local
对于配置文件中定义的每个镜像，创建一个子树合并提交来更新该镜像。
默认情况下，如果没有要进行的更改，则不会创建任何提交。可以使用--allow-empty参数强制创建提交。
mirror-tool update
执行与update-local相同的更新，但还将提交推送到任何配置的远程目标。
目前，GitLab是唯一支持的目标。有关GitLab集成的更多信息，请参阅下面的配置参考。
当使用此命令向GitLab推送时，建议在GitLab CI/CD管道内运行它。该命令将使用CI环境中预定义的环境变量来确定如何连接到GitLab。如果在其他上下文中使用，则必须显式设置许多环境变量。
mirror-tool promote
对于之前由update创建的任何合并请求，创建额外的合并请求（s），将相同的更改提升到配置中定义的其他分支（s）。
此命令可用于实现多层部署/更新工作流程，例如
- 每当镜像仓库发生变化时，创建一个更新它们的MR（通过
mirror-tool update），目标为testing分支。 - 通过某种方式（在mirror-tool范围之外）对该MR进行某些预合并或后合并测试。
- 在将MR提交到
testing分支后，创建一个新的MR，将相同的更改提升到stable分支（通过mirror-tool promote）。
该命令仅对通过mirror-tool update创建的更改进行操作。
与update一样，GitLab目前是该命令的唯一支持目标。
mirror-tool gitlab-ci-yml
生成一个推荐的配置的.gitlab-ci.yml片段，以便将mirror-tool集成到GitLab管道中。
建议将生成的配置放入自己的YAML文件中，并使用include关键字包含该文件。
此命令的输出受.mirror-tool.yaml配置的影响。在更改与GitLab相关的配置元素时，重新运行此命令是个好主意。
配置
mirror-tool需要一个配置文件。按照惯例，这应该放在您的顶级超级项目仓库的.mirror-tool.yaml中。
以下示例演示了可用的配置选项。
# Define the repositories to mirror.
mirror:
- url: https://github.com/org/repo1
ref: refs/heads/master
dir: repo1
- url: https://github.com/org/repo2
ref: refs/heads/main
dir: repo2
# Git configuration to be applied when mirror-tool creates commits.
# Any arbitrary config can be set, but this is most commonly needed
# just to set the name/email on merge commits.
git_config:
user.name: "mirror-tool"
user.email: "noreply@example.com"
# Message for generated commits.
# This is a Jinja template.
commitmsg: |-
Merge {{commits[0].revision_abbrev}} to {{mirror.dir}}
{{commits|length}} commit(s) are being merged.
{% for commit in commits %}
- {{ commit.revision_abbrev }} {{ commit.subject }}
{%- endfor %}
# Configures the GitLab merge request integration.
gitlab_merge:
# If enabled, the update command will create/update a GitLab
# merge request whenever a mirrored repo is updated.
enabled: true
# Token used to authenticate with GitLab.
#
# Currently, this token must always be of the format '$SOME_VARIABLE',
# and the token will be accessed from that environment variable at
# runtime. If running from a GitLab CI/CD pipeline, this should be
# set as a protected CI variable.
token: $GITLAB_MIRROR_TOKEN
# Source branch used for merge requests.
# WARNING: update will do force pushes to this branch!
src: latest
# Target branch used for merge requests.
# The following example supposes that the target branch is used
# to perform some kind of deployment.
dest: deploy
# Title for the merge request.
# This is a Jinja template.
title: "Deploy changes [{{ datetime_day }}]"
# Any desired labels to add onto the merge request.
labels:
- deploy
# Description for the merge request.
# This is a Jinja template.
description: |-
Automated update of dependencies generated by
{{ env.CI_JOB_URL }}.
Submitting this merge request will trigger a deployment.
# Comment(s) to be added when a merge request is created or updated.
# Can be used to ping reviewers.
# If omitted, comments won't be added.
# These are Jinja templates.
comment:
create: "@some-team: please review and submit."
update: "@some-team: merge request has been updated, please re-review."
# Configures GitLab promotion between branches.
# A list of (src, dest) branch pairs with other config.
# Most config has the same meaning as in gitlab_merge.
gitlab_promote:
- src: stage
dest: prod
title: "Promote from stage to prod [{{datetime_day}}]"
token: $GITLAB_MIRROR_TOKEN
labels:
- promote
description: |-
Automated promotion of {{ src_mr.web_url }} to prod.
Jinja上下文
一些配置元素在上文中被描述为Jinja模板。以下变量可在模板中使用
env（字典）
- 在调用
mirror-tool时的所有环境变量。 - 如果在GitLab CI/CD中运行，可以用来访问CI/CD变量。
- 示例：
{{ env.CI_JOB_URL }}=>https://gitlab.example.com/someteam/somerepo/-/jobs/6366493
datetime_iso8601（字符串）
- 当前的UTC日期/时间，以ISO8601格式，具有秒精度。
- 示例：
2022-05-10T05:28:26Z
datetime_minute（字符串）
- 当前的UTC日期/时间，具有分钟精度。
- 示例：
2022-05-10 05:28
datetime_day（字符串）
- 当前的UTC日期。
- 示例：
2022-05-10
datetime_week（字符串）
- 当前的UTC年和周。
- 示例：对于2022年的第19周，为
2022wk19。
updates（列表[UpdateInfo]）（仅限更新）
在大多数Jinja上下文中，对于update和update-local命令，这是一个以下形式的对象列表
UpdateInfo(
mirror=Mirror(
url="https://github.com/rohanpm/mirror-tool",
ref="refs/heads/main",
dir="mirror-tool"
),
# Objects representing commits included in the update, starting
# with the most recent.
#
# If there is a large number of commits being handled, some may be
# elided from this list.
commits=[
Commit(
revision="472b7797518b963f8ab381c39858c18b2b784c2e",
revision_abbrev="472b779",
author_name="Rohan McGovern",
author_email="rohan@mcgovern.id.au",
author_email_local="rohan",
author_datetime=datetime.datetime(2022, 5, 26, 0, 24, 37),
committer_name="Rohan McGovern",
committer_email="rohan@mcgovern.id.au",
committer_email_local="rohan",
committer_datetime=datetime.datetime(2022, 5, 26, 0, 37, 37),
subject="Raise test coverage to 100%",
body="Do this, that and some other\nthings as well.",
url="https://github.com/rohanpm/mirror-tool/commit/472b7797518b963f8ab381c39858c18b2b784c2e",
),
...,
],
# Total number of commits in the update (may be more than len(commits)
# if some were elided).
commit_count=4,
# Number of commits omitted from 'commits' object.
# For example, if an update pulled 200 commits, only the most recent 20
# may appear in 'commits', and this value will be set to 180.
commit_elided_count=0,
)
在commitmsg的Jinja上下文中，由于只有一个更新正在处理，因此updates未定义。相反，所有上述UpdateInfo字段都直接包含在上下文中。
src_mr（字典）（仅限提升）
一个合并请求对象，现在正在提升；即由mirror-tool创建并提交到一个分支的合并请求，现在由mirror-tool提升到另一个分支。
此对象格式的详细信息可以在GitLab API文档中找到。
仅适用于promote命令。
许可证
本程序是免费软件：您可以在自由软件基金会发布的GNU通用公共许可证的条款下重新分发和/或修改它，无论是许可证的第3版，还是（根据您的选择）该许可证的任何后续版本。
下载文件
下载适用于您平台的文件。如果您不确定选择哪一个，请了解有关安装包的更多信息。