ansible.builtin.git 模块 – 从 Git 检出部署软件（或文件）

注意

此模块是 ansible-core 的一部分，包含在所有 Ansible 安装中。在大多数情况下，即使不指定 collections 关键字，您也可以使用简短的模块名称 git。但是，我们建议您使用 完全限定的集合名称 (FQCN) ansible.builtin.git，以便轻松链接到模块文档并避免与可能具有相同模块名称的其他集合冲突。

摘要

• 管理git存储库的检出以部署文件或软件。

需求

以下需求在执行此模块的主机上是必需的。

• git>=1.7.1（命令行工具）

参数

参数	注释
accept_hostkey 布尔值	将确保或不确保“ -o StrictHostKeyChecking=no”作为 ssh 选项存在。 请注意，这会禁用针对中间人攻击的保护。 使用 OpenSSH >= 7.5 的用户可能希望将 ssh_opts 设置为 StrictHostKeyChecking=accept-new，它不会消除中间人攻击问题，但会将其限制在第一次尝试。 选项 false ← (默认) true
accept_newhostkey 布尔值 添加到 ansible-core 2.12 中	从 OpenSSH 7.5 开始，可以使用“-o StrictHostKeyChecking=accept-new”，它更安全，并且只接受不存在或相同的密钥。如果为 true，请确保“ -o StrictHostKeyChecking=accept-new”作为 ssh 选项存在。 选项 false ← (默认) true
archive 路径	指定带有扩展名的存档文件路径。如果指定，则会创建包含源树树结构的指定格式的存档文件。允许的存档格式 [“zip”、“tar.gz”、“tar”、“tgz”]。 这将从本地目录克隆并执行 git archive，因为并非所有 git 服务器都支持 git archive。
archive_prefix 字符串 添加到 ansible-base 2.10 中	指定要在存档中添加到每个文件路径的前缀。需要指定 archive。
bare 布尔值	如果为 true，则存储库将被创建为裸存储库，否则它将是具有工作区的标准存储库。 选项 false ← (默认) true
clone 布尔值	如果为 false，即使本地不存在存储库，也不要克隆它。 选项 false true ← (默认)
depth 整数	创建一个浅克隆，其历史记录被截断为指定的修订次数。最小可能值为 1，否则将被忽略。需要 *git>=1.9.1*才能正常工作。
dest 路径 / 必需	存储库应检出的路径。这等效于 git clone [repo_url] [directory]。在 repo 中命名的存储库不会附加到此路径，并且目标目录必须为空。此参数是必需的，除非 clone 设置为 false。
executable 路径	要使用的 git 可执行文件的路径。如果未提供，则将使用解析二进制路径的常规机制。
force 布尔值	如果为 true，则将丢弃工作存储库中任何已修改的文件。在 0.7 之前，这始终为 true，并且无法禁用。在 1.9 之前，默认值为 true。 选项 false ← (默认) true
gpg_allowlist 别名：gpg_whitelist 列表 / 元素=字符串 添加到 Ansible 2.9 中	要与 GPG 签名提交的指纹进行比较的可信 GPG 指纹列表。 仅当 verify_commit=yes 时使用。 由于此功能依赖于 git 的 --raw 标志到 verify-commit 和 verify-tag，因此需要 Git 2.6+ 版本。 别名 gpg_allowlist 在 2.17 版本中添加。 别名 gpg_whitelist 已弃用，将在 2.21 版本中移除。 默认值： []
key_file 路径	指定目标主机上可选的私钥文件路径，用于检出。 这确保 ssh_opts 中存在 ‘IdentitiesOnly=yes’。
recursive 布尔值	如果 false，则将克隆存储库时不使用 --recursive 选项，跳过子模块。 选项 false true ← (默认)
reference 字符串	参考仓库（参见“git clone –reference …”。）
refspec 字符串	添加要获取的额外 refspec。如果 version 设置为任何分支或标签都无法访问的 *SHA-1*，则可能需要此选项来指定包含 *SHA-1* 的 ref。使用与 git fetch 命令相同的语法。例如值为“refs/meta/config”。
remote 字符串	远程名称。 默认值： "origin"
repo 别名：name 字符串 / 必需	git、SSH 或 HTTP(S) 协议的 git 仓库地址。
separate_git_dir 路径 在 Ansible 2.7 中添加	放置克隆仓库的路径。如果指定，则 Git 仓库可以与工作树分开。
single_branch 布尔值 在 ansible-core 2.11 中添加	仅克隆到指定修订版本顶端的历史记录。 选项 false ← (默认) true
ssh_opts 字符串	git 将在用作协议时传递给 ssh 的选项，它通过 git 的 GIT_SSH/GIT_SSH_COMMAND 环境变量工作。 对于较旧的版本，它会将 GIT_SSH_OPTS（特定于此模块）添加到上面的变量中，或者通过包装器脚本。 其他选项可以添加到此列表中，例如 key_file 和 accept_hostkey。 例如值为“ -o StrictHostKeyChecking=no”（尽管此特定选项最好由 accept_hostkey 设置）。 该模块确保始终存在 ‘BatchMode=yes’ 以避免提示。
track_submodules 布尔值	如果 true，子模块将跟踪其主分支（或 .gitmodules 中指定的其他分支）上的最新提交。如果 false，子模块将保留在主项目指定的修订版本中。这相当于为 git submodule update 指定 --remote 标志。 选项 false ← (默认) true
umask 任意	在进行任何检出或任何其他存储库维护之前要设置的 umask。
update 布尔值	如果 false，则不从原始存储库检索新修订版本。 像 archive 这样的操作将在现有的（旧的）存储库上工作，并且可能不会响应对 version 或 remote 选项的更改。 选项 false true ← (默认)
verify_commit 布尔值	如果 true，则在克隆或检出 version 时，验证 GPG 签名提交的签名。这需要安装 git 版本 >= 2.1.0。提交必须已签名，并且公钥必须存在于 GPG 密钥环中。 选项 false ← (默认) true
version 字符串	要检出的存储库版本。这可以是文字字符串 HEAD、分支名称、标签名称。它也可以是 *SHA-1* 哈希，在这种情况下，如果给定的修订版本尚不可用，则需要指定 refspec。 默认值： "HEAD"

属性

属性	支持	描述
check_mode	支持：完全支持	可以在 check_mode 下运行并返回更改状态预测，而无需修改目标，如果不受支持，则将跳过操作。
diff_mode	支持：完全支持	在 diff 模式下，将返回有关已更改内容（或可能需要在 check_mode 下更改的内容）的详细信息
platform	平台： posix	可以对其进行操作的目标操作系统/系列

备注

注意

• 如果任务似乎挂起，首先验证远程主机是否在 known_hosts 中。SSH 将提示用户授权与远程主机的首次联系。为了避免此提示，一种解决方案是使用 accept_hostkey 选项。另一种解决方案是在调用 git 模块之前，使用以下命令将远程主机公钥添加到 /etc/ssh/ssh_known_hosts 中：ssh-keyscan -H remote_host.com >> /etc/ssh/ssh_known_hosts。

示例

- name: Git checkout
  ansible.builtin.git:
    repo: 'https://foosball.example.org/path/to/repo.git'
    dest: /srv/checkout
    version: release-0.22

- name: Read-write git checkout from github
  ansible.builtin.git:
    repo: [email protected]:mylogin/hello.git
    dest: /home/mylogin/hello

- name: Just ensuring the repo checkout exists
  ansible.builtin.git:
    repo: 'https://foosball.example.org/path/to/repo.git'
    dest: /srv/checkout
    update: no

- name: Just get information about the repository whether or not it has already been cloned locally
  ansible.builtin.git:
    repo: 'https://foosball.example.org/path/to/repo.git'
    dest: /srv/checkout
    clone: no
    update: no

- name: Checkout a github repo and use refspec to fetch all pull requests
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible-examples.git
    dest: /src/ansible-examples
    refspec: '+refs/pull/*:refs/heads/*'

- name: Create git archive from repo
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible-examples.git
    dest: /src/ansible-examples
    archive: /tmp/ansible-examples.zip

- name: Clone a repo with separate git directory
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible-examples.git
    dest: /src/ansible-examples
    separate_git_dir: /src/ansible-examples.git

- name: Example clone of a single branch
  ansible.builtin.git:
    repo: https://github.com/ansible/ansible-examples.git
    dest: /src/ansible-examples
    single_branch: yes
    version: master

- name: Avoid hanging when http(s) password is missing
  ansible.builtin.git:
    repo: https://github.com/ansible/could-be-a-private-repo
    dest: /src/from-private-repo
  environment:
    GIT_TERMINAL_PROMPT: 0 # reports "terminal prompts disabled" on missing password
    # or GIT_ASKPASS: /bin/true # for git before version 2.3.0, reports "Authentication failed" on missing password

返回值

常用返回值已在 此处 记录，以下是此模块特有的字段

键	描述
after 字符串	更新期间检索到的存储库的最后一次提交修订版本。 返回：成功 示例： "4c020102a9cd6fe908c9a4a326a38f972f63a903"
before 字符串	存储库更新之前的提交修订版本，“null”表示新存储库。 返回：成功 示例： "67c04ebe40a003bda0efb34eacfb93b0cafdf628"
git_dir_before 字符串	如果 .git 目录的路径已更改，则包含其原始路径。 返回：成功 示例： "/path/to/old/git/dir"
git_dir_now 字符串	如果 .git 目录的路径已更改，则包含其新路径。 返回：成功 示例： "/path/to/new/git/dir"
remote_url_changed 布尔值	包含 True 或 False，指示远程 URL 是否已更改。 返回：成功 示例： true
warnings 字符串	如果由于 git 版本过旧而导致请求的功能不可用，则会列出警告。 返回：错误 示例： "git version is too old to fully support the depth argument. Falling back to full checkouts."

作者

• Ansible核心团队

• Michael DeHaan

集合链接

• 问题追踪器
• 仓库（源代码）
• 通信