Cómo configurar CI/CD para una aplicación Atlassian Forge

La integración continua y la implementación continua (CI/CD) automatizan el proceso de implementación de cambios de código, lo que ayuda a los equipos de software a entregar actualizaciones más rápidamente y aumentar la confiabilidad. Es una parte esencial de cómo la mayoría de los equipos prueban y envían software en la actualidad.

En Adamam , configurar CI/CD es una de las primeras cosas que hacemos con un nuevo proyecto porque creemos que es importante poder construir y probar nuestras aplicaciones en un entorno controlado. Como todos trabajamos de forma remota, CI/CD es una forma de alinear a nuestros desarrolladores con las partes interesadas o con nuestros clientes, y con canalizaciones automáticas esto se puede hacer casi en tiempo real. 

Después de algunas pruebas y errores, hemos desarrollado un flujo de trabajo de CI/CD que funciona muy bien para nuestro equipo. Estoy escribiendo este tutorial para ayudar a otros desarrolladores de la comunidad de Atlassian a replicar nuestro proceso. Bitbucket Pipelines le brinda una manera fácil de configurar CI/CD directamente desde su repositorio de código. Si lo ha probado, me encantaría saber qué piensa y qué le ha funcionado bien.

Forge, la plataforma de desarrollo de aplicaciones en la nube de Atlassian, le permite implementar aplicaciones directamente en la infraestructura de Atlassian en lugar de autohospedarse. Forge también incluye entornos integrados y comandos CLI para el desarrollo local, la puesta en escena y la implementación en producción. 

En este tutorial, aprenderá cómo crear una aplicación de Atlassian Forge desde cero y cómo configurar un flujo de trabajo completo de integración continua e implementación continua mediante Bitbucket Pipelines.

Antes de que empieces

Este tutorial funciona en varios productos de Atlassian Cloud: Jira, Confluence, Bitbucket y Forge . Las cuatro herramientas se interconectan para crear el flujo de trabajo completo de extremo a extremo:

  • Forge es donde compilará y alojará su aplicación.
  • Confluence es donde se instalará la aplicación Forge.
  • Jira es donde configurará una acumulación de tareas para realizar un seguimiento del trabajo de desarrollo de su aplicación. Podrá ver los resultados de la implementación de su canalización de CI/CD directamente en el problema. 
  • Bitbucket es donde administrará el control de versiones y creará su canalización de CI/CD.

Configuración del proyecto Jira y el repositorio de Bitbucket

Usaremos Jira Cloud para crear una acumulación de tareas que permita a todo un equipo colaborar en el proyecto de la aplicación. Vinculado a Bitbucket, Jira facilitará la colaboración entre desarrolladores, evaluadores, expertos en scrum, propietarios de productos y partes interesadas.

En este tutorial, veremos cómo sucede la magia de CI/CD con cada confirmación y envío de código. 

Si desea continuar, cree un nuevo proyecto de Jira (el de este ejemplo se llama DEMO) y un repositorio de Bitbucket similar al que se vincula a continuación.

Creación de la cartera de proyectos en Jira Software Cloud

En la configuración que se muestra a continuación, hay 2 problemas en la cartera de proyectos de Jira:

  • DEMO-2: Crear la aplicación Forge
  • DEMO-3: Crear la configuración de canalizaciones de Bitbucket

Estas tareas se utilizarán para realizar un seguimiento de nuestro trabajo y las confirmaciones de código. Al vincular Jira y Bitbucket Cloud, podremos ver confirmaciones de código, resultados de integración continua y resultados de implementación continua directamente en cada tarea de Jira.

S4E | Solutions for Everyone - Chile - 1

Creación de la aplicación Forge

Comienza siguiendo el tutorial de Confluence Hello World en la documentación para desarrolladores de Atlassian:  

Si es la primera vez que usa Forge, no olvide instalar Node.js y Docker antes de instalar Forge. Consulte la guía de introducción .

1/ Crea tu aplicación Forge

Cree una aplicación basada en la plantilla de macro Confluence.

Forge proporciona varios entornos en los que implementa la aplicación. Este tutorial utiliza el valor predeterminado de la CLI, el entorno de desarrollo. Obtenga más información sobre los entornos de ensayo y producción .

  1. Navegue hasta el directorio donde desea crear la aplicación. Allí se creará un nuevo subdirectorio con el nombre de la aplicación.
  2. Crea tu aplicación ejecutando:
  3. forjar crear
    1. Introduzca un nombre para su aplicación (hasta 50 caracteres). Por ejemplo, hola-mundo-aplicación .
    2. Seleccione la categoría del kit de interfaz de usuario .
    3. Seleccione la plantilla de macro de confluencia .
  4. Cambie al subdirectorio de la aplicación para ver los archivos de la aplicación:
  5. cd hola-mundo-aplicación
S4E | Solutions for Everyone - Chile - 2

2/ Instala tu aplicación Forge

Para usar su aplicación, debe estar instalada en un sitio de Atlassian. El comando de implementación de forge crea, compila e implementa su código; también informará cualquier error de compilación. Luego, el comando forge install instala la aplicación implementada en un sitio de Atlassian con el acceso a la API requerido.

:información:Tenga en cuenta que debe ejecutar el comando de implementación de falsificación antes de la instalación de falsificación porque una instalación vincula su aplicación implementada a un sitio de Atlassian.

  1. Navegue al directorio de nivel superior de la aplicación e implemente su aplicación ejecutando:
  2. forjar desplegar
  3. Instale su aplicación ejecutando:
  4. instalación de falsificación
  5. Seleccione su producto Atlassian con las teclas de flecha y presione la tecla Intro.
  6. Introduzca la URL de su sitio de desarrollo. Por ejemplo, ejemplo.atlassian.net . ( Vea una lista de sus sitios activos en la administración de Atlassian ).

Una vez que aparece el mensaje de instalación exitosa , su aplicación está instalada y lista para usar en el sitio especificado. Puede eliminar su aplicación del sitio ejecutando el forge uninstallcomando.

S4E | Solutions for Everyone - Chile - 3

3/ Ver su aplicación Forge

Con su aplicación instalada, es hora de ver la aplicación en una página.

  1. Edite una página de Confluence en su sitio de desarrollo.
  2. Abra el menú de inserción rápida escribiendo /el título de su macro en la página. Una vez que comience a escribir el título / Forge aplicación para , la macro con su nombre aparecerá en el menú de inserción rápida.
  3. Seleccione su macro del menú para agregarla a la página.
  4. Publicar la página.

Su aplicación hello world ahora está instalada en su sitio de desarrollo. La aplicación debería mostrarse en la página como la imagen a continuación.

S4E | Solutions for Everyone - Chile - 4

Configuración de canalizaciones de Bitbucket

Bitbucket Pipelines es un servicio de CI/CD integrado integrado en Bitbucket. Le permite compilar, probar e incluso implementar automáticamente su código en función de un archivo de configuración en su repositorio.

:información:Consulte la guía de introducción a Pipelines de Bitbucket

La integración continua es la práctica de fusionar cambios con frecuencia en la rama principal, utilizando verificaciones de compilación para probar posibles problemas antes de implementar los cambios. La implementación continua y la entrega continua describen los pasos que siguen, cuando los cambios de código se implementan en producción. La diferencia entre los dos es que la implementación continua está completamente automatizada.

:información:Obtenga más información sobre la integración continua frente a la entrega frente a la implementación

S4E | Solutions for Everyone - Chile - 5

1/ Agregue dependencias de desarrollo para su aplicación Forge

Deberá modificar el archivo package.json de la aplicación Forge para agregar las dependencias adecuadas para Forge y otros marcos.

"devDependencies": {
    "@forge/cli": "^4.3.2",
    "@types/jest": "^27.4.1",
    "@types/node": "^16.0.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "@typescript-eslint/parser": "^4.23.0",
    "eslint": "^7.32.0",
    "eslint-plugin-react-hooks": "^4.2.0",
    "typescript": "^4.0.0"
  },

Su archivo package.json ahora debería verse así:

{
  "name": "confluence-macro-ui-kit",
  "version": "1.0.5",
  "main": "index.js",
  "license": "MIT",
  "private": true,
  "scripts": {
    "lint": "./node_modules/.bin/eslint src/**/* || npm run --silent hook-errors",
    "hook-errors": "echo '\\x1b[31mThe build failed because a Forge UI hook is being used incorrectly. Forge UI hooks follow the same rules as React Hooks but have their own API definitions. See the Forge documentation for details on how to use Forge UI hooks.\n' && exit 1"
  },
  "devDependencies": {
    "@forge/cli": "^4.3.2",
    "@types/jest": "^27.4.1",
    "@types/node": "^16.0.0",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0",
    "@typescript-eslint/parser": "^4.23.0",
    "eslint": "^7.32.0",
    "eslint-plugin-react-hooks": "^4.2.0",
    "typescript": "^4.0.0"
  },
  "dependencies": {
    "@forge/ui": "1.2.1"
  }
}

2/ Configura la Integración Continua en tu pipeline

Para configurar sus canalizaciones con Bitbucket, debe crear un archivo bitbucket-pipelines.yml en la carpeta hello-world-app .

:información:Atlassian proporciona una herramienta de validación donde puede probar su configuración.

Debido a que una aplicación de Forge se basa en Node.js, la imagen base de Docker para la configuración de su canalización también debe ser Node.js. Usaremos una versión LTS de Node.js, versión 16.14.2.

image:
  name: node:16.14.2

Ahora configuraremos dos pasos paralelos en la tubería en la rama maestra:

  1. Crea la aplicación,
  2. Compruebe la pelusa del código.

También usaremos cachés para reducir el tiempo de ejecución de la canalización. Se necesitan dos variables de repositorio de Bitbucket para ejecutar comandos de Forge desde la canalización para iniciar sesión en la cuenta de Atlassian:

  • $EMAIL: la variable para almacenar el correo electrónico de su cuenta de Atlassian,
  • $TOKEN: la variable para almacenar su token API de Atlassian .

El archivo bitbucket-pipelines.yml ahora debería verse así:

image:
  name: node:16.14.2
pipelines:
  # For MASTER, Build, Test, Code Linting and Deploy to staging only
  branches:
    master:
      - parallel:
        - step:
            name: Run Build
            caches:
              - node
            script:
              - cd hello-world-app
              - npm install
        - step:
            name: Check Code Linting
            script:
              - cd hello-world-app
              - npm install
              - node_modules/.bin/forge settings set usage-analytics false
              # EMAIL AND TOKEN are Bitbucket Repository Variables
              - node_modules/.bin/forge login -u $EMAIL -t $TOKEN
              - node_modules/.bin/forge lint
            caches:
              - node

Hasta ahora, hemos configurado la integración continua de su aplicación Forge. Ahora continuemos con la configuración de implementación continua.

3/ Configure la implementación continua en su tubería

Ahora debemos agregar un paso en la configuración de canalización para implementar la aplicación de Forge en el entorno de prueba. La implementación en el entorno de prueba será automática; en este caso, no habrá interacción humana.

  - step:
      name: Deploy to Staging
      deployment: staging
      caches:
        - node
      script:
        - cd hello-world-app
        - npm install
        - node_modules/.bin/forge settings set usage-analytics false
        - node_modules/.bin/forge login -u $EMAIL -t $TOKEN
        - node_modules/.bin/forge deploy -e staging
        - node_modules/.bin/forge install --site YOURSITE.atlassian.net* --product confluence --non-interactive -e staging
        # if installed, we need to run --upgrade option
        #- node_modules/.bin/forge install --upgrade --site YOURSITE.atlassian.net --product confluence --non-interactive -e staging

* Reemplaza TU SITIO con el nombre de tu sitio

También podemos agregar un paso final para implementar la aplicación Forge en el entorno de producción. La implementación en el entorno de prueba NO será automática: será necesario hacer clic para elegir implementar en el entorno de producción.

  - step:
     name: Deploy to Production
     trigger: manual
     deployment: production
     caches:
       - node
     script:
       - cd hello-world-app
       - npm install
       - node_modules/.bin/forge settings set usage-analytics false
       - node_modules/.bin/forge login -u $EMAIL -t $TOKEN
       - node_modules/.bin/forge deploy -e production

El archivo bitbucket-pipelines.yml ahora debería verse así:

########################################################
#         Adadam | Atlassian Forge CI/CD demo          #
#          Bitbucket Pipelines CONFIGURATION           #
########################################################
image:
  name: node:16.14.2
pipelines:
  # For MASTER, Build, Test, Code Linting and Deploy to staging only
  branches:
    master:
      - parallel:
        - step:
            name: Run Build
            caches:
              - node
            script:
              - cd hello-world-app
              - npm install
        - step:
            name: Check Code Linting
            script:
              - cd hello-world-app
              - npm install
              - node_modules/.bin/forge settings set usage-analytics false
              # EMAIL AND TOKEN are Bitbucket Repository Variables
              - node_modules/.bin/forge login -u $EMAIL -t $TOKEN
              - node_modules/.bin/forge lint
            caches:
              - node
      - step:
          name: Deploy to Staging
          deployment: staging
          caches:
            - node
          script:
            - cd hello-world-app
            - npm install
            - node_modules/.bin/forge settings set usage-analytics false
            - node_modules/.bin/forge login -u $EMAIL -t $TOKEN
            - node_modules/.bin/forge deploy -e staging
            - node_modules/.bin/forge install --upgrade --site YOURSITE.atlassian.net --product confluence --non-interactive -e staging
            # if installed no need to install again = NEED IMPROVEMENTS
            #- node_modules/.bin/forge install --upgrade --site YOURSITE.atlassian.net --product confluence --non-interactive -e staging
      - step:
         name: Deploy to Production
         trigger: manual
         deployment: production
         caches:
           - node
         script:
           - cd hello-world-app
           - npm install
           - node_modules/.bin/forge settings set usage-analytics false
           - node_modules/.bin/forge login -u $EMAIL -t $TOKEN
           - node_modules/.bin/forge deploy -e production

Un aviso importante: a partir de ahora, las aplicaciones de Forge solo pueden ser propiedad de un solo usuario de Atlassian y estar administradas por ellas. Es por eso que estamos usando su correo electrónico y token para autenticar y autorizar en la canalización.

En el futuro, Forge planea agregar una mejor compatibilidad con CI/CD a través de tokens de implementación ( siga la hoja de ruta aquí ) y también permitir que varios usuarios tengan una aplicación de Forge (https://trello.com/c/4pLKOPNA/4-multi-user -propiedad de la aplicación). 

Dejar que suceda la magia: comprometerse y empujar

Después de escribir la configuración de canalización, ahora es el momento de agregar, confirmar y enviar su código fuente a un repositorio de Bitbucket.

1/ Primero regrese a la carpeta raíz donde creó su aplicación:

cd ..

2/ Crear un repositorio de Bitbucket y clonarlo. Por ejemplo:

git clone https://dlauberton@bitbucket.org/adadamfr/adadam-forge-cicd-example.git

3/ Agrega el código fuente de tu aplicación usando Git:

git add hello-world-app

4/ Confirma tu código fuente (y no olvides usar la clave de emisión de Jira Cloud “DEMO-2…” en tu mensaje de confirmación)

git commit -m"DEMO-2: forge app created"

5/ Finalmente, envíe su código fuente al repositorio de Bitbucket:

git push

El comando push activará la canalización y podrá seguir la ejecución de la canalización directamente en la interfaz de usuario de Bitbucket Pipelines.

S4E | Solutions for Everyone - Chile - 6

Ahora divirtámonos y cambiemos algo de código en la aplicación Hello World. Con tu editor favorito, abre el archivo ./hello-world-app/src/index.jsxy reemplaza la palabra “mundo” por tu nombre.

Hay un pequeño cambio que debemos hacer después de la primera vez que se ejecuta la canalización. Inicialmente, la aplicación Hello World no estaba instalada en su sitio de Atlassian Cloud, por lo que la detuvimos explícitamente como parte del script de canalización a través de esta línea:

node_modules/.bin/forge install --upgrade --site YOURSITE.atlassian.net --product confluence --non-interactive -e staging

Ahora que la canalización se ha ejecutado una vez, la aplicación está instalada en nuestro sitio y no es necesario volver a instalarla. Así que comentamos la línea del paso Implementar para ensayo.

# - node_modules/.bin/forge install --upgrade --site YOURSITE.atlassian.net --product confluence --non-interactive -e staging

¡En sus marcas, listos, fuera! Confirma tus cambios:

git commit hello-world-app/src/index.jsx -m"DEMO-2: forge app changes"

git commit bitbucket-pipelines.yml -m"DEMO-3: bitbucket pipeline improvements"

Y envíe sus cambios a su repositorio de Bitbucket:

git push

¡Se activará automáticamente una nueva ejecución en sus Pipelines!

Ahora, edite la página que creó anteriormente para agregarle la aplicación Hello World. Como verá, tendrá 2 aplicaciones diferentes: una existe en el entorno de desarrollo y la otra existe en el entorno de prueba.

S4E | Solutions for Everyone - Chile - 7

Aquí hay un pequeño video donde puedes ver la magia suceder.  :después:https://www.youtube.com/embed/ATr74yyskkY?feature=oembed

Visualización de resultados de confirmación, compilación e implementación en Jira Cloud

Debido a que usamos una clave de incidencia de Jira Cloud en nuestro mensaje de confirmación, y debido a que ambos sitios (Jira Cloud y Bitbucket Cloud) están vinculados, podemos ver las confirmaciones, compilaciones y resultados de implementación directamente en cada incidencia de Jira. ¡Esta es realmente una característica útil!

Después de abrir el problema DEMO-2 y hacer clic en el enlace de confirmación, todas las confirmaciones se enumeran de la siguiente manera.

S4E | Solutions for Everyone - Chile - 8

También se enumeran todas las implementaciones, simplemente cambiando a la pestaña adecuada.

S4E | Solutions for Everyone - Chile - 9

En el proyecto Jira, también hay una vista completa de Implementaciones donde todas las implementaciones son visibles en una línea de tiempo. Esto ayuda a los gerentes de proyectos a visualizar todas las implementaciones para cada problema de una manera simple.

S4E | Solutions for Everyone - Chile - 10

Ir más lejos…

Ahora tiene una canalización de CI/CD en funcionamiento para su aplicación Atlassian, lo que le permite enviar rápidamente cambios de código para que las partes interesadas e incluso los clientes puedan probarlo. Como siguiente paso, ¿por qué no ejecutar pruebas automatizadas en su aplicación para asegurarse de que todos obtengan la misma experiencia de usuario? Agregar pruebas continuas a la integración continua y la implementación continua será el siguiente paso importante. 

Cypress.io es un marco de prueba completo de extremo a extremo y ayuda a los desarrolladores a configurar y escribir pruebas, ejecutar pruebas automáticamente y obtener registros e informes después de ejecutar las pruebas automáticas. Si tienes curiosidad y quieres descubrir Cypress.io en profundidad, echa un vistazo a este artículo que escribí relacionado con un caso de uso específico de un cliente mientras trabajaba para iDalko.

Autor: Damien Lauberton

Somos S4E: Solutions for Everyone, Gold Solution Partner de Atlassian y Select Partner de AWS visítanos y conoce más sobre soluciones digitales para tu compañía.

Nos puedes encontrar en redes sociales, ¡Síguenos para tener actualizaciones diarias! LinkedIn YouTubeFacebook y Twitter

S4E cuenta con un equipo de soporte personal certificado en herramientas Atlassian y AWS.