Introducción

¿Qué es .github?

.github es un directorio en la raíz de un repositorio que GitHub trata de forma especial: busca ahí (y solo ahí, con rutas fijas) un conjunto de archivos que configuran comportamiento de la plataforma — no del código de tu aplicación. Nada de lo que hay en .github se ejecuta como parte de tu build; es metadata y automatización que GitHub interpreta directamente o que dispara sus propios sistemas (Actions, Dependabot, el renderizado de issues).

Un repo con un .github bien armado:

• Corre CI/CD automáticamente en cada push o PR (GitHub Actions).
• Exige que ciertas personas revisen ciertos archivos antes de mergear (CODEOWNERS).
• Guía a quien reporta un bug o una vulnerabilidad con el formulario correcto (issue templates, SECURITY.md).
• Mantiene sus dependencias al día sin intervención manual (Dependabot).
• Le da contexto de convenciones del proyecto a un asistente de IA (Copilot instructions).

Mapa de la carpeta

flowchart TD
    G[".github/"] --> W["workflows/*.yml<br/>GitHub Actions"]
    G --> A["actions/*<br/>Composite actions"]
    G --> IT["ISSUE_TEMPLATE/*<br/>Formularios de issues"]
    G --> DT["DISCUSSION_TEMPLATE/*"]
    G --> PRT["PULL_REQUEST_TEMPLATE.md"]
    G --> CO["CODEOWNERS"]
    G --> SEC["SECURITY.md"]
    G --> CONTRIB["CONTRIBUTING.md"]
    G --> COC["CODE_OF_CONDUCT.md"]
    G --> SUP["SUPPORT.md"]
    G --> FUND["FUNDING.yml"]
    G --> DEP["dependabot.yml"]
    G --> COP["copilot-instructions.md"]
    G --> OTHER["labeler.yml, release-drafter.yml,<br/>settings.yml (terceros)"]

La regla general de ubicación: todo va dentro de .github/, en la rama por defecto del repositorio (normalmente main). Algunos archivos (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, SUPPORT.md) también son válidos en la raíz del repo o en docs/, pero .github/ es la ubicación recomendada porque no ensucia la raíz.

Por qué GitHub le da tratamiento especial

Cuando alguien abre una issue, crea un PR o visita la pestaña de “Community” de tu repo, GitHub busca activamente estos archivos para:

1. Mostrar un botón de “New issue” con templates en vez de un textarea vacío.
2. Precompletar la descripción del PR con tu template.
3. Marcar el repo con un ✅ de “salud de la comunidad” cuando tiene CONTRIBUTING, CODE_OF_CONDUCT, LICENSE, etc.
4. Asignar revisores automáticamente según CODEOWNERS.
5. Mostrar la pestaña “Security” con tu política si existe SECURITY.md.

Nada de esto requiere que instales nada: es comportamiento nativo de la plataforma, gratis, con solo poner el archivo en el lugar correcto.

El repositorio especial .github de organización

Además de la carpeta, existe un repositorio con el nombre literal .github que podés crear a nivel de organización (github.com/tu-org/.github). Los community health files que pongas ahí (en .github/ o en su raíz) se aplican como fallback a todos los repos de la organización que no tengan su propio archivo. Volvemos sobre esto en detalle en el capítulo 7.

Qué NO cubre este curso

• Branch protection rules, required status checks y reglas de merge: viven en la configuración del repo (Settings → Branches), no en archivos de .github. Los mencionamos solo donde se relacionan directamente (p. ej. cómo CODEOWNERS habilita “Require review from Code Owners”).
• GitHub Pages y CNAME: no son parte de .github.

Cómo está organizado el curso

Los capítulos 2 a 6 son GitHub Actions (el tema más extenso y el que más apalancamiento tiene). Los capítulos 7 a 9 son comunidad y seguridad. Los capítulos 10 a 12 son templates y Dependabot. Los capítulos 13 y 14 son automatización con Actions oficiales y Copilot. El capítulo 15 integra todo en un .github completo.

---

Anterior → Índice · Siguiente → Capítulo 2: GitHub Actions — fundamentos