Escenarios: el crecimiento de ACME Corp

​

Etapa 1: un repositorio

initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Postgres and Redis
    run: |
      sudo apt-get update -qq
      sudo apt-get install -y postgresql redis-server libpq-dev
      sudo systemctl enable --now postgresql redis-server
      sudo -u postgres createuser -s "$USER"

maintenance:
  - name: Install gems and prepare the database
    run: |
      bundle install
      bin/rails db:prepare

knowledge:
  - name: lint
    contents: bundle exec rubocop
  - name: test
    contents: bundle exec rspec
  - name: startup
    contents: bin/rails server -p 3000

​

Etapa 2: varios repositorios con dependencias compartidas

​

“¿Un blueprint por aplicación o solo uno para la CLI de desarrollo?”

• Agrega los cinco repositorios al Environment para que todos se clonen en la instantánea.
• Coloca la configuración compartida entre repositorios una sola vez en el blueprint de la organización: entornos de ejecución, Docker, nombres de host locales y credenciales para el registro interno.
• Dale a cada repositorio su propio blueprint del repositorio para sus propias dependencias y sus propias entradas de knowledge (comandos de lint, test e inicio).

​

El blueprint de la organización

initialize:
  - name: Install Ruby 3.3
    uses: github.com/ruby/setup-ruby@v1
    with:
      ruby-version: "3.3"

  - name: Install Node.js 20
    uses: github.com/actions/setup-node@v4
    with:
      node-version: "20"

  - name: Install Docker and Compose
    run: |
      curl -fsSL https://get.docker.com | sh
      sudo usermod -aG docker "$USER"

  - name: Local hostnames for the development CLI
    run: |
      for host in acme.local portal.acme.local sso.acme.local; do
        grep -q " $host$" /etc/hosts \
          || echo "127.0.0.1 $host" | sudo tee -a /etc/hosts > /dev/null
      done

maintenance:
  - name: Authenticate to the internal registry
    run: |
      bundle config set --global https://gems.acme.internal "$ACME_REGISTRY_TOKEN"
      npm config set //npm.acme.internal/:_authToken "$ACME_REGISTRY_TOKEN"

post-build:
  - name: Verify the stack comes up
    run: |
      acme up --detach
      acme status
      acme down

1. initialize frente a maintenance. Docker, los entornos de ejecución y los nombres de host forman parte de la configuración única del sistema, por lo que van en initialize. Las credenciales del registro deben actualizarse en cada compilación periódica, por lo que van en maintenance. El CLI de acme no aparece aquí a propósito. Está dentro de acme-devtools, y los pasos de la organización se ejecutan antes de que se clone cualquier repositorio, por lo que se instala desde el blueprint de ese propio repositorio (se muestra a continuación). Esa instalación se ejecuta durante la compilación y se conserva en la instantánea, desde donde cualquier otro repositorio puede usarla.
2. post-build es la gran ventaja de las configuraciones con varios repositorios. Se ejecuta después de que todos los repositorios se hayan clonado y configurado, así que es el único lugar donde puedes validar que toda la pila arranca en conjunto. Un código de salida distinto de cero hace fallar la compilación, por lo que detectas una pila rota en tiempo de compilación en lugar de a mitad de la sesión. Consulta post-build.
3. Los secretos pertenecen a la organización, no a cada repositorio. Un ACME_REGISTRY_TOKEN en la pestaña Secrets del blueprint de la organización sirve para el bundle install y el npm install de todos los repositorios.

​

Los blueprints de repositorio

initialize: |
  ./bin/install            # añade `acme` al PATH para toda la instantánea

maintenance: |
  acme docs:index          # actualiza el índice de documentación interna en cada compilación

knowledge:
  - name: cli
    contents: |
      `acme` manages every local service. Common commands:
        acme up <service>     start a service and its dependencies
        acme status           list running services
        acme docs:search <q>  search internal ACME engineering documentation
      Prefer `acme docs:search` over guessing at conventions.

maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: startup
    contents: |
      The portal needs SSO running first:
        acme up sso
        acme up portal
      Then visit https://portal.acme.local

​

Si, en cambio, tus servicios están en un monorepo

​

Etapa 3: varias organizaciones — el blueprint de Enterprise

• Todo el tráfico pasa por un proxy corporativo, con una autoridad de certificación interna.
• Todos los paquetes provienen de Artifactory, nunca de registros públicos.
• Todos los Environments deben tener instaladas las herramientas de la empresa para analizar dependencias y detectar secretos.
• Python es 3.12 y Node.js es 20 en toda la empresa, sin excepciones.

initialize:
  - name: Corporate certificate authority and proxy
    run: |
      sudo cp "$FILE_ACME_CA_CERT" /usr/local/share/ca-certificates/acme-ca.crt
      sudo update-ca-certificates
      cat <<'EOF' >> ~/.bashrc
      export HTTPS_PROXY=http://proxy.acme.internal:8080
      export NO_PROXY=localhost,127.0.0.1,.acme.internal
      export NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/acme-ca.crt
      export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
      EOF

  - name: Standard Python runtime
    uses: github.com/actions/setup-python@v5
    with:
      python-version: "3.12"

  - name: Security tooling
    run: |
      pip install bandit safety
      curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sh

maintenance:
  - name: Point every package manager at Artifactory
    run: |
      pip config set global.index-url \
        "https://devin:$ARTIFACTORY_TOKEN@artifactory.acme.internal/api/pypi/pypi/simple/"
      npm config set registry https://artifactory.acme.internal/api/npm/npm/
      npm config set //artifactory.acme.internal/api/npm/npm/:_authToken "$ARTIFACTORY_TOKEN"

knowledge:
  - name: security-policy
    contents: |
      All dependencies must resolve through artifactory.acme.internal.
      Never add a public registry to a lockfile or a CI configuration.

​

De qué se encarga ahora cada nivel

​

Cómo operarlo

• Actualizar Python de 3.12 a 3.13 requiere editar una sola línea y hacer una reconstrucción a nivel Enterprise, que se propaga a todas las organizaciones.
• Cuando un equipo necesita una credencial diferente — por ejemplo, si la organización de Data tiene su propio realm de Artifactory — ese equipo define un secreto de la organización con el mismo nombre, y anula el secreto de Enterprise.
• Para supervisar la adopción de blueprints en las distintas organizaciones, consulta Estado del despliegue.

​

Decidir dónde va cada cosa

• Poner todo en el blueprint de un solo repositorio. Los demás repositorios no reciben entradas de knowledge, y un solo paso roto hace que toda la configuración parezca inestable.
• Duplicar herramientas compartidas en cada repositorio. Cuando dos repositorios instalan versiones distintas de la misma herramienta global, prevalece la última en ejecutarse. En su lugar, coloca la herramienta en el blueprint de la organización.
• Omitir la verificación entre repositorios. Cuando tus repositorios solo funcionan juntos, post-build es el único lugar donde se demuestra que lo hacen: antes de que empiece una sesión, no durante ella.

​

Páginas relacionadas

• Configuración declarativa — orden de compilación, instantáneas y solución de problemas
• Referencia de la plantilla — todos los campos, incluidos post-build y clone
• Biblioteca de plantillas — blueprints para copiar y pegar según el lenguaje y el registro
• Workspaces y monorepos — el equivalente para monorepos de la Etapa 2
• Descripción general del Environment de Enterprise — la Etapa 3 en detalle