Atlantis

Español

English

Español

English

Apariencia

Pruebas localmente ​

Estas instrucciones son para ejecutar Atlantis localmente en tu propia computadora para que puedas probarlo con tus propios repositorios antes de decidir si instalarlo de forma más permanente.

TIP

Si quieres configurar una instalación de Atlantis lista para producción, lee Deployment.

Pasos:

Instalar Terraform ​

terraform debe estar en el $PATH para Atlantis. Descarga desde Terraform

shell
unzip path/to/terraform_*.zip -d /usr/local/bin

Descargar Atlantis ​

Obtén la versión más reciente desde GitHub y descomprímela.

Descargar Ngrok ​

Atlantis necesita ser accesible en algún lugar al que github.com/gitlab.com/bitbucket.org o tu instalación de GitHub/GitLab Enterprise puedan llegar. Una manera de lograr esto es con ngrok, una herramienta que reenvía tu puerto local a un hostname público aleatorio.

Download ngrok y unzip.

Inicia ngrok en el puerto 4141 y toma nota del hostname que te da:

bash
./ngrok http 4141

En una pestaña nueva (donde pronto iniciarás Atlantis) crea una variable de entorno con el hostname de ngrok:

bash
URL="https://{YOUR_HOSTNAME}.ngrok.io"

Crear un Webhook Secret ​

GitHub y GitLab usan webhook secrets para que los clientes puedan verificar que los webhooks provienen de ellos.

Crea una cadena aleatoria de cualquier longitud (puedes usar random.org) y establece una variable de entorno:

shell
SECRET="{YOUR_RANDOM_STRING}"

Agregar webhook ​

Toma la URL que ngrok mostró y crea un webhook en tu repo de GitHub, GitLab o Bitbucket:

Webhook de GitHub o GitHub Enterprise ​

Expand
  • Ve a la configuración de tu repo
  • Selecciona Webhooks o Hooks en la barra lateral
  • Haz clic en Add webhook
  • establece Payload URL en tu URL de ngrok con /events al final. Ej. https://c5004d84.ngrok.io/events
  • verifica de nuevo que agregaste /events al final de tu URL.
  • establece Content type en application/json
  • establece Secret en tu cadena aleatoria
  • selecciona Let me select individual events
  • marca las casillas
    • Pull request reviews
    • Pushes
    • Issue comments
    • Pull requests
  • deja Active marcado
  • haz clic en Add webhook

Webhook de GitLab o GitLab Enterprise ​

Expand
  • Ve a la página principal de tu repo
  • Haz clic en Settings > Webhooks en la barra lateral
  • establece URL en tu URL de ngrok con /events al final. Ej. https://c5004d84.ngrok.io/events
  • verifica de nuevo que agregaste /events al final de tu URL.
  • establece Secret Token en tu cadena aleatoria
  • marca las casillas
    • Push events
    • Comments
    • Merge Request events
  • deja Enable SSL verification marcado
  • haz clic en Add webhook

Webhook de Bitbucket Cloud (bitbucket.org) ​

Expand
  • Ve a la página principal de tu repo
  • Haz clic en Settings en la barra lateral
  • Haz clic en Webhooks bajo la sección WORKFLOW
  • Haz clic en Add webhook
  • Ingresa "Atlantis" para Title
  • Establece URL en tu URL de ngrok con /events al final. Ej. https://c5004d84.ngrok.io/events
  • Verifica de nuevo que agregaste /events al final de tu URL.
  • Mantén Status como Active
  • No marques Skip certificate validation porque NGROK tiene un cert válido.
  • Selecciona Choose from a full list of triggers
  • Bajo Repositoryunmarca todo
  • Bajo Issues deja todo unmarcado
  • Bajo Pull Request, selecciona: Created, Updated, Merged, Declined y Comment created
  • Haz clic en SaveBitbucket Webhook

Webhook de Bitbucket Server (también conocido como Stash) ​

Expand
  • Ve a la página principal de tu repo
  • Haz clic en Settings en la barra lateral
  • Haz clic en Webhooks bajo la sección WORKFLOW
  • Haz clic en Create webhook
  • Ingresa "Atlantis" para Name
  • Establece URL en tu URL de ngrok con /events al final. Ej. https://c5004d84.ngrok.io/events
  • Verifica de nuevo que agregaste /events al final de tu URL.
  • Establece Secret en tu cadena aleatoria
  • Bajo Pull Request, selecciona: Opened, Source branch updated, Merged, Declined, Deleted y Comment added
  • Haz clic en SaveBitbucket Webhook

Webhook de Gitea ​

Expand
  • Haz clic en Settings > Webhooks en la barra superior y luego en la barra lateral
  • Haz clic en Add webhook > Gitea (los webhooks de Gitea son específicos del servicio, pero esto funciona)
  • establece Target URL en http://$URL/events (o https://$URL/events si estás usando SSL) donde $URL es donde Atlantis está alojado. Asegúrate de agregar /events
  • verifica de nuevo que agregaste /events al final de tu URL.
  • establece Secret en el Webhook Secret que generaste previamente
    • NOTE Si estás agregando un webhook a múltiples repositorios, cada repositorio necesitará usar el mismo secret.
  • Selecciona Custom Events...
  • Marca las casillas
    • Repository events > Push
    • Issue events > Issue Comment
    • Pull Request events > Pull Request
    • Pull Request events > Pull Request Comment
    • Pull Request events > Pull Request Reviewed
    • Pull Request events > Pull Request Synchronized
  • Deja Active marcado
  • Haz clic en Add Webhook
  • Consulta Next Steps

Crear un access token para Atlantis ​

Recomendamos usar un usuario de CI dedicado o crear un nuevo usuario llamado @atlantis que realice todas las acciones de API, sin embargo, para pruebas, puedes usar tu propio usuario. Aquí crearemos el access token que Atlantis usa para comentar en el pull request y establecer estados de commit.

Access Token de GitHub o GitHub Enterprise ​

  • Crea un Personal Access Token
  • crea un token con alcance repo
  • establece el token como una variable de entorno
shell
TOKEN="{YOUR_TOKEN}"

Access Token de GitLab o GitLab Enterprise ​

shell
TOKEN="{YOUR_TOKEN}"

Access Token de Bitbucket Cloud (bitbucket.org) ​

  • sigue BitBucket Cloud: Create an app password
  • Etiqueta la contraseña como "atlantis"
  • Selecciona Pull requests: Read y Write para que Atlantis pueda leer tus pull requests y escribir comentarios en ellos
  • establece el token como una variable de entorno
shell
TOKEN="{YOUR_TOKEN}"

Access Token de Bitbucket Server (también conocido como Stash) ​

  • Haz clic en tu avatar en la parte superior derecha y selecciona Manage account
  • Haz clic en HTTP access tokens en la barra lateral
  • Haz clic en Create token
  • Nombra el token atlantis
  • Dale al token permisos de proyecto Read y permisos de pull request Write
  • Elige una opción de Expiry Do not expire o Expire automatically
  • Haz clic en Create y establece el token como una variable de entorno
shell
TOKEN="{YOUR_TOKEN}"

Access Token de Gitea ​

  • Ve a "Profile and Settings" > "Settings" en Gitea (arriba a la derecha)
  • Ve a "Applications" bajo "User Settings" en Gitea
  • Crea un token bajo "Manage Access Tokens" con los siguientes permisos:
    • issue: Read and Write
    • repository: Read and Write
  • Guarda el access token

Iniciar Atlantis ​

Ya casi estás listo para iniciar Atlantis, solo establece dos variables más:

bash
USERNAME="{the username of your GitHub, GitLab or Bitbucket user}"
REPO_ALLOWLIST="$YOUR_GIT_HOST/$YOUR_USERNAME/$YOUR_REPO"
# ex. REPO_ALLOWLIST="github.com/runatlantis/atlantis"
# If you're using Bitbucket Server, $YOUR_GIT_HOST will be the domain name of your
# server without scheme or port and $YOUR_USERNAME will be the name of the **project** the repo
# is under, **not the key** of the project.

Ahora puedes iniciar Atlantis. El comando exacto difiere según tu host de Git:

Comando de GitHub ​

bash
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"

Comando de GitHub Enterprise ​

bash
HOSTNAME=YOUR_GITHUB_ENTERPRISE_HOSTNAME # ex. github.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gh-user="$USERNAME" \
--gh-token="$TOKEN" \
--gh-webhook-secret="$SECRET" \
--gh-hostname="$HOSTNAME" \
--repo-allowlist="$REPO_ALLOWLIST"

Comando de GitLab ​

bash
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--repo-allowlist="$REPO_ALLOWLIST"

Comando de GitLab Enterprise ​

bash
HOSTNAME=YOUR_GITLAB_ENTERPRISE_HOSTNAME # ex. gitlab.runatlantis.io
atlantis server \
--atlantis-url="$URL" \
--gitlab-user="$USERNAME" \
--gitlab-token="$TOKEN" \
--gitlab-webhook-secret="$SECRET" \
--gitlab-hostname="$HOSTNAME" \
--repo-allowlist="$REPO_ALLOWLIST"

Comando de Bitbucket Cloud (bitbucket.org) ​

bash
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--repo-allowlist="$REPO_ALLOWLIST"

Comando de Bitbucket Server (también conocido como Stash) ​

bash
BASE_URL=YOUR_BITBUCKET_SERVER_URL # ex. http://bitbucket.mycorp:7990
atlantis server \
--atlantis-url="$URL" \
--bitbucket-user="$USERNAME" \
--bitbucket-token="$TOKEN" \
--bitbucket-webhook-secret="$SECRET" \
--bitbucket-base-url="$BASE_URL" \
--repo-allowlist="$REPO_ALLOWLIST"

Azure DevOps ​

Se requiere un certificado y una clave privada si se usa autenticación Basic para webhooks.

bash
atlantis server \
--atlantis-url="$URL" \
--azuredevops-user="$USERNAME" \
--azuredevops-token="$TOKEN" \
--azuredevops-webhook-user="$ATLANTIS_AZUREDEVOPS_WEBHOOK_USER" \
--azuredevops-webhook-password="$ATLANTIS_AZUREDEVOPS_WEBHOOK_PASSWORD" \
--repo-allowlist="$REPO_ALLOWLIST"
--ssl-cert-file=file.crt
--ssl-key-file=file.key

Gitea ​

bash
atlantis server \
--atlantis-url="$URL" \
--gitea-user="$ATLANTIS_GITEA_USER" \
--gitea-token="$ATLANTIS_GITEA_TOKEN" \
--gitea-webhook-secret="$ATLANTIS_GITEA_WEBHOOK_SECRET" \
--gitea-base-url="$ATLANTIS_GITEA_BASE_URL" \
--gitea-page-size="$ATLANTIS_GITEA_PAGE_SIZE" \
--repo-allowlist="$REPO_ALLOWLIST"
--ssl-cert-file=file.crt
--ssl-key-file=file.key

Crear un pull request ​

Crea un pull request para que puedas probar Atlantis.

TIP

Podrías agregar un recurso null como prueba:

hcl
resource "null_resource" "example" {}

O simplemente modifica los espacios en blanco en un archivo.

Autoplan ​

Deberías ver a Atlantis registrando que recibió el webhook y deberías ver la salida de terraform plan en tu repo.

Atlantis intenta averiguar el directorio en el que hacer plan según los archivos modificados. Si necesitas personalizar los directorios en los que Atlantis se ejecuta o los comandos que ejecuta si estás usando workspaces o archivos .tfvars, consulta atlantis.yaml Reference.

Plan manual ​

Para ejecutar manualmente plan en un directorio o workspace específico, comenta en el pull request usando las flags -d o -w:

shell
atlantis plan -d mydir
atlantis plan -w staging

Para agregar argumentos adicionales al terraform plan subyacente puedes usar:

shell
atlantis plan -- -target=resource -var 'foo=bar'

Apply ​

Si quieres ejecutar apply, escribe un comentario: atlantis apply. Puedes usar las flags -d o -w para apuntar Atlantis a un plan específico. De lo contrario intenta aplicar el plan para el directorio raíz.

Logs en tiempo real ​

La salida de terraform en tiempo real para tu comando se puede encontrar haciendo clic en la verificación de estado para un proyecto dado en un PR, que enlaza con la UI de transmisión de logs. Esta es una UI de terminal donde puedes ver tus comandos ejecutándose en tiempo real.

Próximos pasos ​

  • Si las cosas están funcionando como se espera puedes Ctrl-C el comando atlantis server y el comando ngrok.
  • Con suerte Atlantis está funcionando con tu repo y estás listo para continuar con un deployment listo para producción.
  • Si no está funcionando como se espera, puede que necesites personalizar cómo se ejecuta Atlantis con un archivo atlantis.yaml. Consulta casos de uso de atlantis.yaml.
  • Revisa nuestra documentación completa para más detalles.

Copyright Atlantis a Series of LF Projects, LLC. Para los términos de uso del sitio web, la política de marcas y otras políticas del proyecto, consulta LF Projects, LLC Policies.