Bitbucket Cloud: ручной pipeline с проверяемыми параметрами

Задача: ручной запуск без произвольной команды

Команде нужен pipeline, который запускают по запросу и которому передают понятный параметр. Свободная строка с именем окружения неудобна: опечатка обнаруживается поздно, а при неосторожной подстановке значение может стать частью команды. Начните с небольшого разрешённого набора и проверки внутри шага.

В учебном примере пользователь выбирает sandbox-a или sandbox-b. Pipeline только проверяет выбор и сохраняет файл с выбранным значением и SHA коммита. Он не подключается к серверу, не собирает приложение и ничего не развёртывает. Сначала нужно подтвердить контракт запуска, затем отдельно проектировать полезную операцию.

Инструкция относится к Bitbucket Cloud Pipelines и облачному Linux Docker-исполнению. Для Bitbucket Data Center такого встроенного сервиса Pipelines нет; переносить этот YAML в другой CI без адаптации нельзя. Cloud обновляется как сервис, поэтому отдельный номер устанавливаемой версии здесь не задаётся. Конфигурация и примеры не являются отчётом о запуске на клиентском репозитории.

Подготовка и границы пилота

Выберите отдельный учебный репозиторий с уже доступным Pipelines. Для ручного запуска требуется право записи в репозиторий. Проверьте остаток сборочных минут и действующие ограничения своего плана: пробные запуски тоже используют ресурсы. Включать платное дополнение ради примера не требуется.

Если используете существующий репозиторий, сохраните исходный bitbucket-pipelines.yml и добавляйте новый custom-раздел, не заменяя рабочие branches, default и definitions. Для первого опыта удобнее отдельная ветка. Не добавляйте ключи SSH, переменные production или deployment-настройки: этот пример в них не нуждается.

Запишите ожидаемые значения параметра и результат: для каждого разрешённого выбора появляется plan.txt с тем же значением и коммитом запуска; неизвестный или пустой параметр останавливает проверку до создания результата. Слово sandbox здесь является нейтральной меткой, а не адресом сервера или правом на среду.

Почему custom, а не первый ручной шаг

Раздел pipelines → custom задаёт отдельный pipeline для явного ручного запуска либо настроенного расписания. Для этого пилота расписание не создавайте. Не пытайтесь поставить trigger: manual на первый шаг обычного pipeline: первый step или stage не может быть ручным.

Параметр TARGET объявляется через variables под именем custom pipeline. default задаёт начальный выбор, allowed-values — предлагаемый набор. Это интерфейс ввода для конкретной процедуры, а не замена разрешениям репозитория. Не передавайте сюда пароли или токены.

Для воспроизводимого разбора сохраняйте исходник YAML вместе с коммитом. Название validate-request должно описывать проверку, а не обещать выпуск приложения: в конфигурации ниже нет шага deploy. Позднее не превращайте его в production-процесс простым добавлением команды в конец без отдельной проверки доступа и отката.

Минимальная конфигурация

Поместите пример в bitbucket-pipelines.yml в корне учебного репозитория. В рабочем файле объединяйте разделы аккуратно: второй ключ pipelines вместо расширения существующего блока создаст неоднозначную конфигурацию. Используйте пробелы для отступов и проверьте YAML редактором.

Образ atlassian/default-image:5 приведён как документированный пример облачной среды. Он не является неизменяемым снимком: для рабочего процесса отдельно выбирайте и контролируйте образ и необходимые инструменты. Наш шаг использует только shell, mkdir, printf и cat; установки пакетов и внешних запросов в нём нет.

Блок case проверяет фактическое значение TARGET до создания файла. Подстановки в командах заключены в кавычки. Здесь параметр не становится именем исполняемой команды, путём к скрипту или произвольным адресом. Не заменяйте эту проверку выполнением eval над пользовательской строкой.

BITBUCKET_COMMIT — встроенная переменная с коммитом сборки. Файл out/plan.txt объявлен артефактом, чтобы результат можно было скачать из запуска. Не сохраняйте в нём секреты и полное окружение контейнера.

image: atlassian/default-image:5

pipelines:
  custom:
    validate-request:
      - variables:
          - name: TARGET
            default: sandbox-a
            allowed-values:
              - sandbox-a
              - sandbox-b
      - step:
          name: Validate selection
          script:
            - |
                set -eu
                case "${TARGET:-}" in
                  sandbox-a|sandbox-b) ;;
                  *) printf 'Unsupported TARGET\n' >&2; exit 2 ;;
                esac
                mkdir -p out
                printf 'target=%s\ncommit=%s\n' "$TARGET" "$BITBUCKET_COMMIT" > out/plan.txt
                cat out/plan.txt
          artifacts:
            - out/plan.txt

Ручной запуск и проверка результата

Сохраните конфигурацию коммитом в учебной ветке. Откройте Pipelines → Run pipeline, выберите нужную ветку и custom pipeline validate-request. Проверьте TARGET перед подтверждением. Другой вариант — запуск из меню конкретного коммита; после старта всегда сверяйте фактический SHA на странице результата.

Для первого запуска оставьте sandbox-a. Откройте журнал шага и скачайте out/plan.txt. В нём должны быть две строки: target с выбранным значением и commit с SHA этого запуска. Затем отдельно запустите sandbox-b и сравните результаты, не смешивая файлы от разных выполнений.

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

Отрицательные проверки и типовые ошибки

Матрица ниже — план контроля для своей среды. Пустое и неподдерживаемое значение можно проверить локально на извлечённом shell-блоке; не нужно ослаблять allowed-values рабочего pipeline ради ввода неправильной строки. Локальный разбор YAML и проверка shell не заменяют проверку конфигурации и исполнения самим Bitbucket.

Если pipeline отсутствует в выборе, проверьте коммит и ветку с нужным YAML и положение custom-раздела. Если шаг завершился до создания файла, прочитайте первую ошибку, а не ищите артефакт от предыдущего запуска. Ошибка загрузки образа и отказ проверки TARGET — разные причины.

Если результат содержит другой коммит, сначала убедитесь, что открыт нужный запуск. Не исправляйте отчёт вручную: он должен объясняться выбранной ревизией и выполненным кодом.

• sandbox-a: успешное завершение и соответствующий target в файле.
• sandbox-b: успешное завершение без подмены предыдущим значением.
• Пустой TARGET: ненулевой код выхода, plan.txt не создан.
• Неизвестное значение: ненулевой код выхода до создания результата.
• Строка с разделителем shell-команд: отклонена как значение, посторонняя команда не выполняется.

Ограничения параметров, артефактов и полномочий

allowed-values помогает ограничить выбор, но разрешение на полезную операцию должно проверяться тем механизмом, который эту операцию выполняет. Пользователь с правом менять исходник способен изменить и проверку. Для реального выпуска отдельно контролируйте ветку, права запуска и доступ к среде; нейтральный TARGET не является deployment environment.

Для конфиденциальных значений используйте предназначенные механизмы переменных и секретов, а не открытый параметр запуска. Не выводите все переменные через env или set для диагностики. В этом пилоте журнал содержит только нейтральную метку и SHA; настоящие учётные данные не нужны.

Артефакты Pipelines хранятся ограниченное время — по текущей документации максимум 14 дней. plan.txt не является постоянным реестром согласований или выпусков. Если нужен длительный учёт, заранее определите отдельное разрешённое хранилище и состав данных, не добавляя сторонний платный сервис автоматически.

Остановка и безопасный откат

Чтобы убрать пилот, удалите только custom pipeline validate-request через обычный коммит либо верните соответствующую правку файла. Сохраните остальные рабочие определения. Если позже для него создавали расписание, отключите и его отдельно: отсутствие ручного запуска в инструкции не доказывает отсутствие фонового расписания.

Проверьте текущие выполнения в интерфейсе Pipelines. Возврат YAML не отменяет уже начатую работу и не удаляет ранее созданные артефакты. Наш пример не меняет внешние системы; если вы добавили собственные действия, порядок их отмены нужно определить отдельно.

После возврата убедитесь, что рабочие pipelines остались доступны и ссылаются на ожидаемую ревизию. Сохраните проверенный шаблон и матрицу входных данных для следующей процедуры. Переход к сборке или развёртыванию начинайте как отдельное изменение, а не как незаметное расширение диагностического шага.