Представим, что у нас есть репозиторий, где хранятся плейбуки и роли Ansible. Делался он долго, старательно и по правилам. И даже если мы перед коммитами проверяем его через линтер, чтобы не сломать хрупкую YAML красоту и перепроверяем не забыли ли мы подчистить секреты с которыми проводили тесты, то рано или поздно подобную ошибку совершит кто-то другой. И вот, чтобы снизить такую вероятность и лишний раз не заниматься правками в Git, чтобы вычистить пароли или поправить форматирование, можно немного обезопасить репозиторий заранее.

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

Готовим инфраструктуру

Для начала нам понадобится Runner - это тот самый трудяга, который будет раз за разом выполнять проверки, которые мы ему зададим. В нашем случае это будет Docker-контейнер. Развернуть его можно как на той же ноде, где стоит и Git, а можно и на любой другой, была бы сетевая связность.

Шаг 1

И так, заходим на нашу машину, где решили разворачивать раннер и создаём dockerfile со следующим содержимым:

FROM docker.gitea.com/runner-images:ubuntu-latest

RUN apt-get update && \
    apt-get install -y yamllint && \
    apt-get install -y wget && \
    wget https://github.com/gitleaks/gitleaks/releases/download/v8.18.4/gitleaks_8.18.4_linux_x64.tar.gz && \
    tar -xzf gitleaks_8.18.4_linux_x64.tar.gz && \
    mv gitleaks /usr/local/bin/ && \
    rm gitleaks_8.18.4_linux_x64.tar.gz && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

За основу берём образ предоставляемый самим gitea и добавляем в него yamllint для проверки синтаксиса и поиска ошибок в YAML-файлах, а также gitleaks, который будет искать забытые пароли, ключи, API и прочие секреты. Сохраняем файл и собираем образ:

docker build -t ubuntu-yamllint:latest .

Шаг 2

Создаём файл docker-compose.yml со следующим содержимым:

version: '3'
services:
  act_runner:
    image: gitea/act_runner:latest
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./runner_data:/data
    environment:
      - GITEA_INSTANCE_URL=https://YOUR_GIT
      - GITEA_RUNNER_REGISTRATION_TOKEN=YOUR_TOKEN
      - GITEA_RUNNER_NAME=my-docker-runner
      - GITEA_RUNNER_LABELS=ubuntu-yamllint:docker://ubuntu-yamllint:latest,ubuntu-latest:docker://docker.gitea.com/runner-images:ubuntu-latest,ubuntu-22.04:docker://docker.gitea.com/runner-images:ubuntu-22.04
    restart: unless-stopped

Здесь важно заполнить две переменные - GITEA_INSTANCE_URL (указать где находится ваш Git-репозиторий) и GITEA_RUNNER_REGISTRATION_TOKEN. Токен можно получить в настройках репозитория, во вкладке Actions -> Runners, нажав кнопку Create new Runner. В этом же меню раннер появится после того, как вы запустите Docker-контейнер.

В переменной GITEA_RUNNER_LABELS указаны несколько лейблов. Я использую только ubuntu-yamllint:latest. Остальные можно удалить, они на работу не влияют, но можно и оставить, так как не мешают они тоже.

Запускаем контейнер и наблюдаем, как он начинает работать:

docker compose up -d
docker ps

Настраиваем пайплайн

Мы подготовили место где будет работать наш пайплайн, теперь очередь самого пайплайна.

Шаг 1

В директории Ansible создадим директорию .gitea/workflows и в ней файл, который можно назвать как угодно, например yamllint_and_pass_check.yml. Запишем в него следующие настройки:

---
name: YAML Lint

on: [push]

jobs:
  yamllint:
    runs-on: ubuntu-yamllint
    steps:
      - name: Checkout linting
        uses: actions/checkout@v4
      - name: Run yamllint with auto-detected config
        run:  yamllint -c .yamllint .
  gitleaks:
    runs-on: ubuntu-yamllint
    steps:
      - name: Checkout passwords leaks
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Run gitleaks
          run: gitleaks detect --source .
...

Суть в следующем, указываем имя, на каком шаге выполняется (в нашем случае на push), какой образ используем и указываем какие задачи выполнить (сами задачи разбиты по шагам, которые также имеют имена).

Но некоторые строки требуют дополнительного пояснения.

uses: actions/checkout@v4 - использует стандартный action GitHub версии 4 (Gitea почти всё берёт оттуда), который означает клон репозитория в рабочую директорию контейнера (по сути git clone). Подробнее про Actions и какие они бывают можно посмотреть здесь.

fetch-depth: 0 - снимает ограничения на глубину истории и скачивает всё, для поиска секретов это важно.

yamllint -c .yamllint . и gitleaks detect --source . - запускают наши проверки.

Шаг 2

И чтобы линтер и gitleaks не указывали на все подряд проблемы (потому что что-то должно быть в таком виде по задумке, а что-то просто невозможно поправить по ряду причин), мы их немного настроим.

Всё в той же директории Ansible создадим файл .yamllint с содержимым:

---
extends: default

ignore: |
  roles/filebeat_install/files/fields.yml
  .gitea/workflows/yamllint.yml

rules:
line-length:
max: 180
...

Тут можно настроить максимальную длину строки, после превышения которой линтер начнёт ругаться, а также указать какие файлы игнорировать при проверке.

Также есть возможность отключать проверку линтером прямо в рабочих файлах, указывая перед нужными строками правило которое применять не нужно:

# yamllint disable-line rule:line-length

Теперь очередь gitleaks. Создаём файл .gitleaks.toml и запишем в него:

[extend]
useDefault = true

[allowlist]
paths = [
  '''roles/logs_settings_on_ptaf/templates/filebeat.yml.j2''',
]

Здесь Также можно указать проверку каких файлов необходимо исключить, если имеется такая необходимость.

Защищаем master-ветку

Заходим в настройки репозитория и видим там вкладку Branches

Там можем или создать новое правило, или отредактировать имеющееся.

Для защиты ветки от вливания в неё непроверенных изменений будет достаточно в разделе Push выставить Disable Push и в разделе Force Push выставить Disable Force Push. А в разделе Pull Request Merge укажем Enable Merge. Также не лишним будет поставить галочку на пункте Administrators must follow branch protection rules, чтобы у админов репозитория не было соблазна обходить общие правила.

Также будет необходимо поставить галочку на пункте Enable Status Check и выбрать проверки, которые должны завершиться успешно, чтобы мёрдж в главную ветку был разрешён. Но выбор этих проверок появится только после хотя бы одного их выполнения.

Заключение

После выполнения всех этих действий мы получаем защиту мастер-ветки от бардака и утечки секретов. Новые пуши должны отправляться в отдельные ветки и уже потом мёрджиться в основную. Но это будет успешно только в том случае, если будут пройдены обе проверки. Можно добавить дополнительные проверки, если таковые нужны. Необходимо просто дополнить dockerfile нужными утилитами и пересобрать образ. Как пример, можно добавить ansiblelint, но, по моему скромному мнению, его проверки слишком уж жёсткие, так как проверяется не только синтаксис, но и правильность использования тех или иных инструментов Ansible, что подойдёт не для всех.