Создание действия контейнера Docker

Введение

В этом руководстве вы узнаете об основных компонентах, необходимых для создания и использования упакованного действия контейнера Docker. Чтобы сосредоточиться в этом руководстве на компонентах, необходимых для упаковки действия, функциональные возможности кода действия будут минимальны. Действие записывает сообщение "Hello World" в журналах или "Hello [имя приветствуемого]" при указании пользовательского имени.

Завершив этот проект, вы должны понять, как создать собственное действие контейнера Docker и протестировать его в рабочем процессе.

В локальных средствах выполнения должна использоваться операционная система Linux и должен быть установлен Docker для выполнения действий с контейнерами Docker. Дополнительные сведения о требованиях локальных средств выполнения см. в разделе "О самостоятельно размещенных средствах выполнения".

Необходимые компоненты

• Необходимо создать репозиторий на GitHub и клонировать его на рабочую станцию. Дополнительные сведения см. в разделе "[AUTOTITLE" и "Создание репозитория](/repositories/creating-and-managing-repositories/cloning-a-repository)".
• Если репозиторий использует Git LFS, необходимо включить объекты в архивы репозитория. Дополнительные сведения см. в разделе Управление объектами LFS Git в архивах репозитория.
• Вы можете найти полезное представление о GitHub Actions, переменных среды и файловой системы контейнера Docker. Дополнительные сведения см. в разделе "[AUTOTITLE" и "Хранение сведений в переменных](/enterprise-cloud@latest/actions/using-github-hosted-runners/about-github-hosted-runners#docker-container-filesystem)".

Создание файла Dockerfile

В новом каталоге hello-world-docker-action создайте файл Dockerfile. Убедитесь, что имя файла имеет прописную букву (используйте прописную букву D, но не прописную букву f), если у вас возникли проблемы. Дополнительные сведения см. в разделе Поддержка Dockerfile для GitHub Actions.

Dockerfile

# Container image that runs your code
FROM alpine:3.10

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Code file to execute when the docker container starts up (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]

# Container image that runs your code
FROM alpine:3.10

# Copies your code file from your action repository to the filesystem path `/` of the container
COPY entrypoint.sh /entrypoint.sh

# Code file to execute when the docker container starts up (`entrypoint.sh`)
ENTRYPOINT ["/entrypoint.sh"]

Создание файла метаданных действия

Создайте новый файл action.yml в каталоге hello-world-docker-action. Дополнительные сведения см. в разделе Синтаксис метаданных для GitHub Actions.

action.yml

# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.who-to-greet }}

# action.yml
name: 'Hello World'
description: 'Greet someone and record the time'
inputs:
  who-to-greet:  # id of input
    description: 'Who to greet'
    required: true
    default: 'World'
outputs:
  time: # id of output
    description: 'The time we greeted you'
runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs.who-to-greet }}

Эти метаданные определяют один входной параметр who-to-greet и один выходной параметр time. Чтобы передать входные данные в контейнер Docker, необходимо объявить входные данные с помощью inputs и передать их в ключевом слове args. Все, что вы включаете в контейнер, передается в контейнер args, но для лучшего обнаружения для пользователей вашего действия мы рекомендуем использовать входные данные.

GitHub создаст образ из образа Dockerfile и выполнит команды в новом контейнере с помощью этого образа.

Написание кода действия

Вы можете выбрать любой базовый образ Docker и, следовательно, любой язык для своего действия. В указанном ниже примере скрипта оболочки используется входная переменная who-to-greet для печати Hello [who-to-greet] в файле журнала.

Затем скрипт получает текущее время и присваивает его выходной переменной, которую смогут использовать действия, выполняемые позже в рамках задания. Чтобы GitHub распознать выходные переменные, необходимо записать их в $GITHUB_OUTPUT файл среды: echo "<output name>=<value>" >> $GITHUB_OUTPUT Дополнительные сведения см. в разделе Команды рабочего процесса для GitHub Actions.

1. Создайте файл entrypoint.sh в новом каталоге hello-world-docker-action.

2. Добавьте в файл entrypoint.sh указанный ниже код.

   entrypoint.sh

   Shell

   #!/bin/sh -l
   
   echo "Hello $1"
   time=$(date)
   echo "time=$time" >> $GITHUB_OUTPUT
   
   

   Если entrypoint.sh выполняется без ошибок, состояние действия имеет значение success. Вы также можете явно задать коды выхода в коде действия, чтобы предоставить состояние действия. Дополнительные сведения см. в разделе Настройка кодов выхода для действий.

3. Сделайте исполняемый entrypoint.sh файл исполняемым файлом. Git предоставляет способ явного изменения режима разрешений файла, чтобы он не сбрасывал каждый раз, когда есть клон/вилка.

   Shell

   git add entrypoint.sh
   git update-index --chmod=+x entrypoint.sh
   

4. При необходимости, чтобы проверить режим разрешений файла в индексе Git, выполните следующую команду.

   Shell

   git ls-files --stage entrypoint.sh
   

   Выходные данные, такие как 100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh означает, что файл имеет разрешение исполняемого файла. В этом примере 755 обозначает разрешение исполняемого файла.

Создание файла README

Чтобы сообщить людям, как применить свое действие, можно создать файл README. Файл сведений наиболее полезен, если вы планируете опубликовать действие в открытом доступе, но может также применяться в качестве напоминания для себя или своей команды.

В каталоге hello-world-docker-action создайте файл README.md со следующими сведениями:

• подробное описание того, что делает действие;
• обязательные входные и выходные аргументы;
• необязательные входные и выходные аргументы;
• секреты, используемые действием;
• переменные среды, используемые действием;
• пример использования действия в рабочем процессе.

README.md

# Hello world docker action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.

## Inputs

## `who-to-greet`

**Required** The name of the person to greet. Default `"World"`.

## Outputs

## `time`

The time we greeted you.

## Example usage

uses: actions/hello-world-docker-action@v2
with:
  who-to-greet: 'Mona the Octocat'

# Hello world docker action

This action prints "Hello World" or "Hello" + the name of a person to greet to the log.

## Inputs

## `who-to-greet`

**Required** The name of the person to greet. Default `"World"`.

## Outputs

## `time`

The time we greeted you.

## Example usage

uses: actions/hello-world-docker-action@v2
with:
  who-to-greet: 'Mona the Octocat'

Фиксация действия, добавление тегов к нему и его отправка в GitHub

В терминале зафиксируйте файлы action.yml, entrypoint.sh, Dockerfile и README.md.

Рекомендуется также добавить тег версии для выпусков действия. Дополнительные сведения о настройке версий действия см. в разделе "Сведения о настраиваемых действиях".

git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1
git push --follow-tags

git add action.yml entrypoint.sh Dockerfile README.md
git commit -m "My first action is ready"
git tag -a -m "My first action release" v1
git push --follow-tags

Тестирование действия в рабочем процессе

Теперь вы готовы протестировать действие в рабочем процессе.

• Если действие находится в частном репозитории, вы можете управлять доступом к нему. Дополнительные сведения см. в разделе "Управление параметрами GitHub Actions для репозитория".

• Общедоступные действия могут использоваться рабочими процессами в любом репозитории.

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

В указанном ниже коде рабочего процесса используется готовое действие hello world в общедоступном репозитории actions/hello-world-docker-action. Скопируйте указанный ниже пример кода рабочего процесса в файл .github/workflows/main.yml, но замените actions/hello-world-docker-action именем репозитория и действия. Вы также можете заменить входное поле who-to-greet на свое имя. Открытые действия можно применять, даже если они не опубликованы в GitHub Marketplace. Дополнительные сведения см. в разделе Публикация действий в GitHub Marketplace.

.github/workflows/main.yml

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - name: Hello world action step
        id: hello
        uses: actions/hello-world-docker-action@v2
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      - name: Hello world action step
        id: hello
        uses: actions/hello-world-docker-action@v2
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

Пример использования частного действия

Скопируйте указанный ниже пример кода рабочего процесса в файл .github/workflows/main.yml в репозитории действия. Вы также можете заменить входное поле who-to-greet на свое имя. Это частное действие не может быть опубликовано в GitHub Marketplace, и его можно использовать только в этом репозитории.

.github/workflows/main.yml

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      # To use this repository's private action,
      # you must check out the repository
      - name: Checkout
        uses: actions/checkout@v4
      - name: Hello world action step
        uses: ./ # Uses an action in the root directory
        id: hello
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

on: [push]

jobs:
  hello_world_job:
    runs-on: ubuntu-latest
    name: A job to say hello
    steps:
      # To use this repository's private action,
      # you must check out the repository
      - name: Checkout
        uses: actions/checkout@v4
      - name: Hello world action step
        uses: ./ # Uses an action in the root directory
        id: hello
        with:
          who-to-greet: 'Mona the Octocat'
      # Use the output from the `hello` step
      - name: Get the output time
        run: echo "The time was ${{ steps.hello.outputs.time }}"

В репозитории перейдите на вкладку Действия и выберите последний запуск рабочего процесса. В разделе Задания или в графе визуализации щелкните Задание для отображения приветствия.

Нажмите кнопку "Hello world action step", и вы увидите "Hello Mona the Octocat" или имя, которое вы использовали для who-to-greet ввода, напечатанного в журнале. Чтобы просмотреть метку времени, нажмите кнопку "Получить время вывода".

Доступ к файлам, созданным действием контейнера

При выполнении действия контейнера он автоматически сопоставляет рабочий каталог по умолчанию (GITHUB_WORKSPACE) в средстве выполнения с /github/workspace каталогом в контейнере. Все файлы, добавленные в этот каталог в контейнере, будут доступны для всех последующих шагов в том же задании. Например, если у вас есть действие контейнера, которое создает проект, и вы хотите отправить выходные данные сборки в качестве артефакта, можно выполнить следующие действия.

workflow.yml

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Output build artifacts to /github/workspace on the container.
      - name: Containerized Build
        uses: ./.github/actions/my-container-action

      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: workspace_artifacts
          path: ${{ github.workspace }}

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      # Output build artifacts to /github/workspace on the container.
      - name: Containerized Build
        uses: ./.github/actions/my-container-action

      - name: Upload Build Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: workspace_artifacts
          path: ${{ github.workspace }}

Дополнительные сведения о передаче выходных данных сборки в качестве артефакта см. в разделе "Хранение и предоставление общего доступа к данным из рабочего процесса".

Примеры действий контейнера Docker для GitHub.com

Вы можете найти множество примеров действий контейнера Docker на GitHub.com.

• github/issue-metrics
• microsoft/infersharpaction
• Microsoft/ps-docs