Nota: Actualmente los ejecutores hospedados en GitHub no se admiten en GitHub Enterprise Server. Puede ver más información sobre la compatibilidad futura planeada en GitHub public roadmap.
Introducción
Esta guía te muestra los pasos mínimos necesarios para desarrollar una acción de contenedor de Docker. Para centrar esta guía en los componentes necesarios para empaquetar la acción, la funcionalidad del código de la acción es mínima. La acción imprime "Hello World" en los registros o "Hello [who-to-greet]"si proporcionas un nombre personalizado.
Una vez que completes este proyecto, deberías comprender cómo crear tu propia acción de contenedor Docker y probarla en un flujo de trabajo.
Los ejecutores auto-hospedados deberán utilizar un sistema operativo Linux y tener Docker instalado para ejecutar las acciones de contenedores de Docker. Para más información sobre los requisitos de los ejecutores autohospedados, consulta "Acerca de los ejecutores autohospedados".
Advertencia: Cuando cree flujos de trabajo y acciones, siempre debe considerar si el código podría ejecutar entradas no confiables de atacantes potenciales. Se tratará a algunos contextos como una entrada no confiable, ya que un atacante podrían insertar su propio contenido malintencionado. Para obtener más información, vea «Fortalecimiento de seguridad para GitHub Actions».
Requisitos previos
- Debes crear un repositorio en GitHub y clonarlo en la estación de trabajo. Para obtener más información, vea «Crear un repositorio nuevo» y «Clonar un repositorio».
- Si el repositorio usa Git LFS, debes incluir los objetos en los archivos del repositorio. Para obtener más información, vea «Administrar los objetos de LFS de Git en los archivos de tu repositorio».
- Puede ser útil tener un entendimiento básico de variables de entorno de las GitHub Actions, y del sistema de archivos de contenedor Docker. Para obtener más información, vea «Almacenamiento de información en variables» y «Utilizar los ejecutores hospedados en GitHub».
Crear un Dockerfile
En el nuevo directorio hello-world-docker-action
, cree un archivo Dockerfile
. Asegúrese de que en el nombre de archivo se usen las mayúsculas adecuadas (una D
mayúscula pero no una f
mayúscula) en caso de que tenga problemas. Para obtener más información, vea «Soporte de Dockerfile para 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"]
Crear un archivo de metadatos de una acción
Cree un archivo action.yml
en el directorio hello-world-docker-action
que ha creado antes. Para obtener más información, vea «Sintaxis de metadatos para Acciones de GitHub».
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 }}
Estos metadatos definen una entrada who-to-greet
y un parámetro de salida time
. Para pasar entradas al contenedor de Docker, debe declarar la entrada mediante inputs
y pasarla en la palabra clave args
. Todo lo que incluya en args
se pasa al contenedor, pero para que a los usuarios les resulte más sencillo descubrir la acción, se recomienda usar entradas.
GitHub compilará una imagen a partir de Dockerfile
y ejecutará comandos en nuevo contenedor con esta imagen.
Escribir el código de la acción
Puedes elegir cualquier imagen de Docker base y, por lo tanto, cualquier idioma para tu acción. En el ejemplo de script del shell siguiente se usa la variable de entrada who-to-greet
para imprimir "Hello [a_quien_se_salude]" en el archivo de registro.
A continuación, el script obtiene la hora actual y la establece como una variable de salida que pueden usar las acciones que se ejecutan posteriormente en un trabajo. Para que GitHub reconozcan variables de salida, debes escribirlas en el archivo de entorno $GITHUB_OUTPUT
: echo "<output name>=<value>" >> $GITHUB_OUTPUT
. Para obtener más información, vea «Comandos de flujo de trabajo para Acciones de GitHub».
-
En el directorio
hello-world-docker-action
, cree un archivoentrypoint.sh
. -
Agregue el código siguiente al archivo
entrypoint.sh
.entrypoint.sh
Shell #!/bin/sh -l echo "Hello $1" time=$(date) echo "time=$time" >> $GITHUB_OUTPUT
#!/bin/sh -l echo "Hello $1" time=$(date) echo "time=$time" >> $GITHUB_OUTPUT
Si
entrypoint.sh
se ejecuta sin errores, el estado de la acción se establece ensuccess
. También puedes establecer explícitamente códigos de salida en el código de tu acción para proporcionar el estado de una acción. Para obtener más información, vea «Establecimiento de códigos de salida para acciones». -
Convierte el archivo
entrypoint.sh
en ejecutable. Git proporciona una manera de cambiar explícitamente el modo de permiso de un archivo para que no se restablezca cada vez que haya una bifurcación o clonación.Shell git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
git add entrypoint.sh git update-index --chmod=+x entrypoint.sh
-
Opcionalmente, para comprobar el modo de permiso del archivo en el índice de Git, ejecute el siguiente comando.
Shell git ls-files --stage entrypoint.sh
git ls-files --stage entrypoint.sh
Una salida como
100755 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 0 entrypoint.sh
significa que el archivo tiene el permiso ejecutable. En este ejemplo,755
indica el permiso ejecutable.
Crear un README
Puedes crear un archivo README para que las personas sepan cómo usar tu acción. Un archivo README resulta más útil cuando planificas el intercambio de tu acción públicamente, pero también es una gran manera de recordarle a tu equipo cómo usar la acción.
En el directorio hello-world-docker-action
, cree un archivo README.md
que especifique la información siguiente:
- Una descripción detallada de lo que hace la acción.
- Los argumentos de entrada y salida obligatorios.
- Los argumentos de entrada y salida opcionales.
- Los secretos que usa la acción.
- Las variables de entorno que usa la acción.
- Un ejemplo de cómo usar la acción en un flujo de trabajo.
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'
Confirmar, etiquetar y subir tu acción a GitHub Enterprise Server
Desde el terminal, confirme los archivos action.yml
, entrypoint.sh
, Dockerfile
y README.md
.
También es recomendable agregar una etiqueta de versión para los lanzamientos de tu acción. Para más información sobre el control de versiones de la acción, consulta "Acercad e las acciones personalizadas".
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
Probar tu acción en un flujo de trabajo
Ahora estás listo para probar tu acción en un flujo de trabajo.
- Cuando una acción está en un repositorio privado, puedes controlar quién puede acceder a ella. Para más información, consulta "Administrar los ajustes de las GitHub Actions de un repositorio". - Cuando una acción está en un repositorio interno, puedes controlar quién puede acceder a ella. Para más información, consulta "Administrar los ajustes de las GitHub Actions de un repositorio".
- Los flujos de trabajo de cualquier repositorio pueden usar acciones públicas.
Nota: GitHub Actions en GitHub Enterprise Server pueden tener acceso limitado a las acciones de GitHub.com o GitHub Marketplace. Para más información, consulta "Administrar el acceso a las acciones desde GitHub.com" y ponte en contacto con el administrador del sitio de GitHub Enterprise.
Ejemplo usando una acción pública
En el código de flujo de trabajo siguiente se usa la acción hello world completada en el repositorio público actions/hello-world-docker-action
. Copie el código de ejemplo de flujo de trabajo siguiente en un archivo .github/workflows/main.yml
, pero reemplace actions/hello-world-docker-action
por el repositorio y el nombre de la acción. También puede reemplazar la entrada who-to-greet
por su nombre.
.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 }}"
Ejemplo usando una acción privada
Copie el código de flujo de trabajo de ejemplo siguiente en un archivo .github/workflows/main.yml
del repositorio de la acción. También puede reemplazar la entrada who-to-greet
por su nombre.
.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 }}"
En el repositorio, haga clic en la pestaña Actions y seleccione la última ejecución de flujo de trabajo. En Jobs o en el gráfico de visualización, haga clic en A job to say hello.
En el registro, debería ver el paso de acción Hola mundo y debería ver "Hello Mona the Octocat", o el nombre que haya usado para la entrada who-to-greet
impreso en el registro. Para ver la marca de tiempo, haz clic en Obtener la hora de salida.
Acceso a los archivos creados por una acción de contenedor
Cuando se ejecuta una acción de contenedor, asignará automáticamente el directorio de trabajo predeterminado (GITHUB_WORKSPACE
) en el ejecutor con el directorio /github/workspace
del contenedor. Los archivos agregados a este directorio en el contenedor estarán disponibles para los pasos posteriores del mismo trabajo. Por ejemplo, si tiene una acción de contenedor que compila el proyecto y desea cargar la salida de compilación como un artefacto, puede seguir estos pasos.
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@v3 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@v3
with:
name: workspace_artifacts
path: ${{ github.workspace }}
Para obtener más información sobre cómo cargar la salida de compilación como un artefacto, vea "Almacenamiento y uso compartido de datos desde un flujo de trabajo".
Acciones de contenedor Docker de ejemplo en GitHub.com
Puedes encontrar muchos ejemplos de acciones de contenedor Docker en GitHub.com.