git

Содержание

git#

Модуль ansible.builtin.git управляет извлечением репозиториев Git для развертывания файлов или программного обеспечения.

Особенности работы#

Для работы модуля на управляемом узле должна быть установлена утилита командной строки git версии не ниже 1.7.1.

Если задача зависает, убедитесь, что узел с репозиторием Git добавлен в файл known_hosts на управляемом узле. SSH может запрашивать подтверждение добавления публичного ключа при первом подключении. Чтобы избежать этого запроса, используйте один из следующих способов:

Используйте параметр accept_hostkey, чтобы разрешить автоматическое добавление ключа.
Добавьте открытый ключ в файл пользователя, от имени которого выполняются задания Ansible, с помощью команды:
```
ssh-keyscan -H remote_host.com >> ~/.ssh/known_hosts
```

Параметры#

accept_hostkey#

Добавление строки -o StrictHostKeyChecking=no в параметры SSH.

Использование этого параметра отключает защиту от атак злоумышленников в канале передачи (MITM, Man In The Middle).

При использовании OpenSSH версии 7.5 и выше рекомендуется использовать параметр accept_newhostkey или указать StrictHostKeyChecking=accept-new через параметр ssh_opts, чтобы ограничить риск атаки MITM при первом подключении.

Возможные значения:

false – не добавлять строку;
true – добавить строку.

Значение по умолчанию: false.

accept_newhostkey#

Добавление строки -o StrictHostKeyChecking=accept-new в параметры SSH (поддерживается при использовании OpenSSH версии 7.5 и выше).

Использование этого параметра безопаснее, чем полное отключение проверки, так как принимает только новые или совпадающие ключи.

Возможные значения:

false – не добавлять строку;
true – добавить строку.

Значение по умолчанию: false.

archive#

Путь к архивному файлу, создаваемому из содержимого репозитория. Поддерживаемые форматы:

zip;
tar;
tar.gz;
tgz.

Архив создается локально на основе клона, поскольку не все серверы Git поддерживают команду git archive.

archive_prefix#: Префикс, добавляемый к пути каждого файла в архиве. Используется только при указании параметра archive.

bare#

Создание пустого (bare) репозитория.

Возможные значения:

false – создание обычного репозитория с рабочим каталогом;
true – создание пустого репозитория.

Значение по умолчанию: false.

clone#

Клонирование репозитория, если он не существует локально.

Возможные значения:

false – не клонировать репозиторий;
true – клонировать, если репозиторий не существует.

Значение по умолчанию: true.

depth#

Выполнение частичного (shallow) клонирования, с загрузкой только указанного количества коммитов.

Минимальное значение: 1.

Для использования параметра требуется Git версии 1.9.1 или выше.

dest#

Обязательный параметр при clone=true.

Путь к каталогу, в котором необходимо разместить репозиторий.

Использование этого параметра эквивалентно команде:

git clone [repo_url] [directory]

Название репозитория, указанного в параметре repo, не добавляется к этому пути, а целевой каталог должен быть пустым.

executable#: Путь к исполняемому файлу git. Если путь не указан, будет использоваться обычный механизм разрешения двоичных путей.

force#

Удаление изменений в рабочем репозитории.

Возможные значения:

false – сохранить изменения;
true – удалить изменения.

Значение по умолчанию: false.

gpg_whitelist#

Список доверенных отпечатков ключей GPG, используемых для проверки подписи коммитов.

Особенности использования:

параметр используется только при verify_commit=true;
для использования необходим Git версии 2.6 и выше, так как параметр применяет аргумент --raw для проверки коммитов (verify-commit) и тегов (verify-tag).

Значение по умолчанию: [] (пустой список).

key_file#

Путь к приватному ключу SSH, используемому для доступа к репозиторию. Указанный ключ должен размещаться на целевом узле.

Использование этого параметра добавляет IdentitiesOnly=yes в ssh_opts.

recursive#

Клонирование подмодулей репозитория.

Возможные значения:

false – не клонировать подмодули;
true – клонировать подмодули.

Значение по умолчанию: true.

reference#

Путь к локальному репозиторию, который будет использоваться в качестве источника.

Использование этого параметра эквивалентно выполнению команды git clone с параметром --reference.

refspec#

Дополнительная ссылка (refspec) для получения объектов из репозитория (используется тот же синтаксис, что и в git fetch).

При version=SHA-1, если SHA-1 недоступен ни из одной ветки или тега, может потребоваться явно указать ссылку, содержащую этот SHA-1.

remote#

Название удаленного репозитория.

Значение по умолчанию: origin.

repo, name#

Обязательный параметр.

Адрес репозитория. Это может быть адрес в формате Git, SSH или HTTP(S).

separate_git_dir#

Путь к каталогу, в котором будут размещены внутренние данные Git.

Если параметр указан, каталог .git не создается в рабочем каталоге проекта, а все данные Git сохраняются по указанному пути. Это позволяет отделить внутренние данные Git от рабочего каталога.

single_branch#

Клонирование истории только указанной ветки.

Возможные значения:

false – клонировать историю всех веток;
true – клонировать историю одной ветки.

Значение по умолчанию: false.

ssh_opts#

Дополнительные параметры, которые модуль передаст Git для использования при подключении по SSH. Эти параметры попадают в переменные окружения GIT_SSH или GIT_SSH_COMMAND, которые используются Git для настройки поведения подключения SSH.

Если используется устаревшая версия, параметры также могут быть добавлены через переменную окружения GIT_SSH_OPTS (которая специфична для данного модуля) или с помощью оберточного сценария (wrapper script).

Например, можно указать параметр -o StrictHostKeyChecking=no (однако, для этого рекомендуется использовать параметр accept_hostkey).

К этому списку могут быть добавлены параметры, устанавливаемые другими параметрами модуля, например, key_file и accept_hostkey.

Важно

Модуль всегда добавляет параметр BatchMode=yes, чтобы избежать появления запросов (например, для ввода пароля).

track_submodules#

Порядок обновления подмодулей при работе с репозиторием.

Возможные значения:

false – отслеживать последнюю фиксацию в основной ветке (или другой ветке, указанной в .gitmodules).
true – использовать версию, указанную в основном проекте. Эквивалентно использованию аргумента --remote при обновлении подмодуля.

Значение по умолчанию: false.

umask#: Значение umask, устанавливаемое перед выполнением операций Git.

update#

Получение изменений из исходного репозитория.

Возможные значения:

false – не получать изменения;
true – получать изменения.

Значение по умолчанию: true.

verify_commit#

Проверка подписи коммита при клонировании или переключении версии.

Для использования параметра необходимо:

Git версии 2.1.0 или выше;
подписанный коммит;
присутствие открытого ключа в связке GPG.

Возможные значения:

false – не проверять подписи.
true – проверять подписи.

Значение по умолчанию: false.

version#

Ветка, тег, хеш SHA-1 или HEAD репозитория, который нужно извлечь.

Значение по умолчанию: HEAD.

Возвращаемые значения#

В этом списке указаны только возвращаемые значения, специфичные для модуля ansible.builtin.git.

after – последняя версия репозитория, полученная во время обновления.

Условия: успешное завершение.
before – версия коммита до обновления репозитория. Для нового репозитория null.

Условия: успешное завершение.
git_dir_before – исходный путь к каталогу .git, если он был изменен.

Условия: успешное завершение.
git_dir_now – новый путь к каталогу .git, если он был перемещен.

Условия: успешное завершение.
remote_url_changed – был ли изменен URL удаленного репозитория.

Условия: успешное завершение.
warnings – список предупреждений, если часть параметров недоступна из-за устаревшей версии git.

Условия: ошибка.

Атрибуты#

Атрибуты определяют функции Ansible, которые может использовать модуль.

Атрибут	Описание
`check_mode`	Модуль поддерживает режим проверки. Модуль может быть использован с параметром `--check` и возвращает предполагаемый результат без выполнения операций.
`diff_mode`	Модуль поддерживает режим сравнения. При использовании `--diff` отображает различия между текущим и предполагаемым состоянием.
`platform`	Модуль поддерживает только POSIX-совместимые ОС.

Примеры#

Для изучения возможностей модуля ознакомьтесь с приведенными ниже примерами.

Клонирование репозитория по HTTPS#

Следующий пример описывает клонирование публичного репозитория по протоколу HTTPS:

---
- name: HTTPS
  ansible.builtin.git:
    repo: https://git.example.com/myproject/myrepo.git
    dest: /tmp/checkout
    version: release-1.0

Клонирование репозитория по SSH#

Следующий пример описывает клонирование с использованием SSH:

---
- name: SSH
  ansible.builtin.git:
    repo: git@git.example.com:myproject/myrepo.git
    dest: /tmp/checkout

Проверка наличия репозитория без обновления#

Следующий пример описывает использование параметра update: no:

---
- name: Just ensuring the repo checkout exists
  ansible.builtin.git:
    repo: https://git.example.com/myproject/myrepo.git
    dest: /tmp/checkout
    update: no

Получение информации о локальном репозитории#

Следующий пример описывает выполнение без клонирования и обновления:

---
- name: Do not clone or update, check information
  ansible.builtin.git:
    repo: git@git.example.com:myproject/myrepo.git
    dest: /tmp/checkout
    clone: no
    update: no

Загрузка через refspec#

Следующий пример описывает использование параметра refspec для загрузки нестандартных ссылок:

---
- name: Use refspec
  ansible.builtin.git:
    repo: https://git.example.com/myproject/myrepo.git
    dest: /tmp/checkout
    refspec: '+refs/pull/*:refs/heads/*'

Создание архива из репозитория#

Следующий пример описывает создание архива:

---
- name: Create archive from repo
  ansible.builtin.git:
    repo: git@git.example.com:myproject/myrepo.git
    dest: /tmp/checkout
    archive: /tmp/ansible.zip

Отделение рабочего каталога#

Следующий пример описывает использование параметра separate_git_dir для отделения каталога .git:

---
- name: Clone a repo with separate git directory
  ansible.builtin.git:
    repo: https://git.example.com/myproject/myrepo.git
    dest: /tmp/checkout
    separate_git_dir: /tmp/repo

Клонирование одной ветки#

Следующий пример описывает клонирование только указанной ветки:

---
- name: Сlone of a single branch
  ansible.builtin.git:
    repo: git@git.example.com:myproject/myrepo.git
    dest: /tmp/checkout
    single_branch: yes
    version: master

Отключение интерактивных запросов#

Следующий пример описывает установку переменной окружения для предотвращения зависания при отсутствии пароля:

---
- name: Avoid hanging when http(s) password is missing
  ansible.builtin.git:
    repo: https://git.example.com/myproject/myrepo.git
    dest: /tmp/checkout
  environment:
    GIT_TERMINAL_PROMPT: 0