Host config

Por qué lo necesita

Un Repositorio tiene exactamente una clave: la que Semaphore usa para clonarlo. Eso basta mientras todo lo que la tarea necesita vive en ese repositorio. En la práctica, una tarea accede a otros lugares, y cada uno de ellos puede exigir una credencial distinta:

Las flechas discontinuas son la brecha: la clave del repositorio no se ofrece a esos servidores, así que la tarea falla con Permission denied o Authentication failed en cuanto llega a ellos. Hasta ahora, las únicas soluciones eran dar a una sola clave acceso a todas partes, o incrustar las credenciales en los archivos del repositorio.

Host config (configuración de hosts) lo resuelve sin tocar el repositorio. Usted le dice a Semaphore "siempre que el proyecto se conecte a este host o a esta URL, usa esa credencial del Almacén de claves". La asignación se aplica a todas las conexiones Git y SSH de la tarea, desde donde quiera que se inicien.

Tiene	Qué hay en el repositorio	Sin asignación	Con asignación
Un submódulo privado en otro servidor Git	.gitmodules apuntando a [email protected]:infra/common.git	git submodule update es rechazado: la clave de despliegue del repositorio principal no se conoce allí	Una asignación Host para gitlab.example.com con la clave permitida en ese servidor
Roles o colecciones privados en el requirements.yml de Ansible	src: https://gitlab.example.com/ansible/role-nginx.git	ansible-galaxy install pide un inicio de sesión y falla	Una asignación URL para https://gitlab.example.com/ansible/ con un token de acceso de GitLab
Módulos privados de Terraform / OpenTofu obtenidos de Git	source = "git::https://github.com/acme/tf-modules.git"	terraform init no puede descargar el módulo	Una asignación URL para https://github.com/acme/ con una clave SSH o un token
Un inventario cuyos hosts necesitan una clave SSH distinta de la del repositorio	Un inventario con db-01.internal, db-02.internal	El inventario solo puede nombrar una clave, y la del repositorio no es la correcta para esos hosts	Una asignación Host para cada nombre de host, o una sola asignación con la clave del inventario para el host que comparten

Una sola asignación sirve para todos estos casos a la vez; no se configura nada por plantilla. Cuando un proyecto no tiene asignaciones, nada cambia: las tareas siguen usando la clave del repositorio, exactamente como antes.

Cómo funciona

Una asignación es una regla con tres partes: con qué debe coincidir (un nombre de host o un prefijo de URL), qué credencial del Almacén de claves usar, y nada más. Semaphore instala las asignaciones del proyecto antes del primer comando Git de una tarea y las retira cuando la tarea termina. Todas las conexiones que la tarea abre, desde su propia clonación hasta un módulo git dentro de un playbook, pasan por ellas.

La página está en el menú del proyecto, debajo de Repositorios. Añadir, editar y eliminar asignaciones requiere el permiso para gestionar los recursos del proyecto, el mismo que necesita el Almacén de claves.

Tipos de asignación

Pulse Add mapping (añadir asignación) y elija con qué debe coincidir la asignación.

Host

Una asignación de tipo Host coincide con un nombre de host SSH, por ejemplo github.com o gitlab.example.com, y necesita una clave SSH. Cada vez que la tarea abre una conexión SSH a ese host, se autentica con la clave asignada: un repositorio o submódulo clonado por SSH, una URL git@host:group/repo.git en requirements.yml y también los hosts de un inventario de Ansible con ese nombre. Cuando la clave tiene un nombre de usuario, se usa como usuario SSH para el host.

URL

Una asignación de tipo URL coincide con la URL https:// o http:// de un repositorio. Puede nombrar un solo repositorio, https://gitlab.example.com/infra/network.git, o terminar en / para cubrir todos los repositorios de un grupo, https://gitlab.example.com/ansible/. Cuando coinciden varias asignaciones, gana la URL más específica, de modo que la asignación de un repositorio concreto prevalece sobre la asignación del grupo que lo contiene.

La credencial decide cómo se accede a la URL:

Credencial	Qué ocurre
Clave SSH	La URL se reescribe en su forma SSH y la conexión se autentica con la clave. El nombre de usuario de la clave es el usuario SSH, git cuando la clave no tiene ninguno.
Inicio de sesión con contraseña	El nombre de usuario y la contraseña se añaden a la URL y se envían por HTTPS. Deje vacío el nombre de usuario para usar un token de acceso personal. Solo una URL https:// acepta esta credencial, de modo que el secreto nunca viaja en texto claro.

La URL no debe contener credenciales propias, espacios, comillas ni el carácter =.

Dónde se aplican las asignaciones

Las asignaciones de un proyecto se instalan antes del primer comando Git de una tarea y permanecen en vigor hasta que esta termina. Cubren:

• la clonación y actualización del repositorio de la plantilla, incluidos sus submódulos;
• los roles y colecciones instalados desde requirements.yml, consulte Requisitos de Galaxy;
• los módulos descargados por terraform init o tofu init;
• los comandos Git iniciados por el propio playbook o script, por ejemplo el módulo git de Ansible;
• el repositorio de un inventario guardado en Git;
• los hosts del inventario, cuando una asignación Host coincide con su nombre;
• la exploración de ramas y playbooks de un repositorio en el formulario de plantilla, y el sondeo de las programaciones que se inician con un nuevo commit.

Las tareas enviadas a un runner remoto reciben las asignaciones junto con la tarea, por lo que allí se comportan de la misma manera.

Una asignación prevalece sobre la entrada del mismo host en la configuración SSH global del servidor (ssh.config_path en la configuración); el resto de entradas de ese archivo siguen funcionando. Las asignaciones necesitan el cliente Git de línea de comandos, que es el predeterminado git_client: cmd_git; con el cliente integrado go_git, una tarea de un proyecto con asignaciones falla con un error explicativo en lugar de usar la credencial equivocada.

Credenciales

Las claves privadas nunca tocan el disco: cada asignación SSH guarda su clave en un agente SSH que vive tanto como la tarea, y la configuración SSH generada solo nombra al agente. Un inicio de sesión con contraseña se pasa a Git a través de su entorno de configuración, no en la línea de comandos, y Git muestra la URL original en el registro de la tarea, así que el secreto no aparece en ninguno de los dos.

Una clave a la que hace referencia una asignación no puede eliminarse; el diálogo de confirmación muestra las asignaciones que la usan. Cambiar el tipo de una clave así a uno que la asignación no pueda usar, por ejemplo convertir la clave SSH de una asignación Host en un inicio de sesión con contraseña, también se rechaza.

Ejemplo

Un playbook vive en GitHub, usa un submódulo de un GitLab autoalojado e instala un rol de un segundo grupo de GitLab mediante requirements.yml:

# requirements.yml
- src: https://gitlab.example.com/ansible/role-nginx.git
  version: v2.1.0

Tres asignaciones hacen que la tarea se ejecute sin ningún cambio en el repositorio:

Tipo	Host o URL	Credencial
Host	github.com	La clave de despliegue del repositorio de GitHub
URL	https://gitlab.example.com/ansible/	Un token de acceso de GitLab, como inicio de sesión con contraseña
URL	https://gitlab.example.com/infra/network.git	La clave SSH autorizada solo en ese repositorio

Copias de seguridad

Las asignaciones forman parte de la copia de seguridad del proyecto. Hacen referencia a su credencial por nombre, de modo que un proyecto restaurado las mantiene vinculadas a las claves restauradas. Como con cualquier clave, el valor secreto en sí no se exporta.