Configurando un CI para Código de Robot usando Acciones GitHub
Un aspecto importante de trabajar en un equipo es ser capaz de probar el código que es enviado a una librería como GitHub. Por ejemplo, el director del proyecto o desarrollador principal podría ejecutar un grupo de unidades de prueba antes de fusionarla a una solicitud de extracción o podría querer asegurarse que todos los códigos en la rama dominante de una librería estén trabajando correctamente
Acciones GitHub es un servicio que permite a los equipos e individuos construyan y ejecuten pruebas de unidades en un código con varias ramas y solicitudes de extracción. Este tipo de servicios son comúnmente conocidos conocidos como servicios de “Continuous Integration”. Este tutorial le enseñará como preparar GitHub Actions en proyectos con códigos en robots.
Nota
Este tutorial asume que el código del robot de tu equipo está alojado en GitHub. Para una introducción a Git y GitHub, por favor vea esta guía de introducción.
Creando una acción
Las instrucciones para llevar a cabo el proceso de CI están almacenados en un archivo YAML. Para crearlo, dé click en “Actions” en la parte superior de su repositorio. Después dé click en hipervínculo de “set up a workflow yourself”.
Ahora será recibido con un editor de texto. Reemplace todo el texto predeterminado con lo siguiente:
# This is a basic workflow to build robot code.
name: CI
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch.
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# This grabs the WPILib docker container
container: wpilib/roborio-cross-ubuntu:2024-22.04
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v4
# Declares the repository safe and not under dubious ownership.
- name: Add repository to git safe directories
run: git config --global --add safe.directory $GITHUB_WORKSPACE
# Grant execute permission for gradlew
- name: Grant execute permission for gradlew
run: chmod +x gradlew
# Runs a single command using the runners shell
- name: Compile and run tests on robot code
run: ./gradlew build
Después, guarde los cambios dando click en botón de “Start commit” en la esquina superior derecha de la pantalla. Puede modificar el mensaje predeterminado si lo desea. Después, de click en el botón verde de “Commit new file”.
El GitHub ahora ejecutará automáticamente una construcción cada vez que un commit sea empujado al principal o se abra una solicitud pull. Para monitorear el estado de cualquier construcción, puedes hacer clic en la pestaña «Acciones» en la parte superior de la pantalla.
Una descompostura del archivo Acciones YAML
Aquí hay un desglose del archivo YAML de arriba. Aunque no se requiere una comprensión estricta de cada línea, algún nivel de comprensión le ayudará a añadir más características y depurar posibles problemas que puedan surgir.
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch.
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
Este bloque de código dicta cuándo se ejecutará la Acción. Actualmente, la acción se ejecutará cuando las confirmaciones se empujen al main o cuando se abran peticiones pull contra la del main.
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-latest
# This grabs the WPILib docker container
container: wpilib/roborio-cross-ubuntu:2024-22.04
Cada flujo de trabajo de Action es hecho por uno o más trabajos ya sea que serán ejecutados (uno después de otro) o en paralelo (al mismo tiempo). En nuestro flujo de trabajo, solo hay un trabajo de “construcción”.
Especificamos que queremos que el trabajo ejecute una máquina virtual de Ubuntu y en un contenedor Docker que contiene JDK, compilador C++ y roboRIO toolchains.
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v4
# Declares the repository safe and not under dubious ownership.
- name: Add repository to git safe directories
run: git config --global --add safe.directory $GITHUB_WORKSPACE
# Grant execute permission for gradlew
- name: Grant execute permission for gradlew
run: chmod +x gradlew
# Runs a single command using the runners shell
- name: Compile and run tests on robot code
run: ./gradlew build
Each job has certain steps that will be executed. This job has four steps. The first step involves checking out the repository to access the robot code. The second step is a workaround for a GitHub Actions issue. The third step involves giving the virtual machine permission to execute gradle tasks using ./gradlew. The final step runs ./gradlew build to compile robot code and run any unit tests.
Agregando un Distintivo de estatus de construcción a un archivo README.md
Es útil agregar una etiqueta CI de estatus en la parte superior del archivo README de su repositorio para revisar rápidamente el estado de la última construcción en la rama principal. Para hacer esto, dé clic en “Actions” en la parte superior de la pantalla y seleccione “CI” en el lado izquierdo de la pantalla. Después, dé clic en el botón de “Create status badge” en la parte superior derecha y copie el código de Markdown de la etiqueta de estado.
Finalmente, pegue el código de Markdown que copió en la parte de arriba de su archivo README, asigne, y presione sus cambios. Ahora, debería de ver la etiqueta de estado de GitHub Actions en la página principal de su repositorio.
