Acerca de las áreas de trabajo de CodeQL

Acerca de las áreas de trabajo de CodeQL

Usa un área de trabajo de CodeQL cuando quieras agrupar varios paquetes de CodeQL. Un caso de uso típico para un área de trabajo de CodeQL es desarrollar un conjunto de paquetes de consultas y bibliotecas de CodeQL que dependan entre sí. Para más Información sobre los paquetes de CodeQL, consulta "Personalización del análisis con paquetes de CodeQL".

La principal ventaja de un área de trabajo de CodeQL es que facilita el desarrollo y mantenimiento de varios paquetes de CodeQL. Cuando se usa un área de trabajo de CodeQL, todos los paquetes de CodeQL del área de trabajo están disponibles como dependencias de origen entre sí al ejecutar un comando de CodeQL que resuelve consultas. Esto facilita el desarrollo, el mantenimiento y la publicación de varios paquetes de CodeQL relacionados.

En la mayoría de los casos, debes almacenar el área de trabajo de CodeQL y los paquetes de CodeQL incluidos en ella en un repositorio de Git. Esto facilita el uso compartido del entorno de desarrollo de CodeQL.

El archivo codeql-workspace.yml

Un archivo yaml codeql-workspace.yml define un área de trabajo de CodeQL. Este archivo contiene un bloque provide y, opcionalmente, bloques ignore y registries.

• El bloque provide contiene una lista de patrones globales que definen los paquetes de CodeQL que están disponibles en el área de trabajo.

• El bloque ignore contiene una lista de patrones globales que definen los paquetes de CodeQL que no están disponibles en el área de trabajo.

• El bloque registries contiene una lista de direcciones URL de GHES y patrones de paquete que controlan qué registro de contenedor se usa para publicar paquetes de CodeQL. Para obtener más información, vea «Publicación y uso de paquetes de CodeQL».

Cada entrada de las secciones provide o ignore debe asignarse a la ubicación de un archivo qlpack.yml. Todos los patrones globales se definen en relación con el directorio que contiene el archivo del área de trabajo. Para obtener una lista de patrones aceptados en este archivo, consulta "@actions/glob".

Por ejemplo, el archivo codeql-workspace.yml siguiente define un área de trabajo que contiene todos los paquetes de CodeQL que se encuentran de forma recursiva en el directorio codeql-packs, excepto los paquetes del directorio experimental. El bloque registries especifica que los paquetes de codeql/\* se deben descargar de https://ghcr.io/v2/, que es el registro de contenedor predeterminado de GitHub. Todos los demás paquetes deben descargarse y publicarse en el registro en GHE_HOSTNAME.

provide:
  - "*/codeql-packs/**/qlpack.yml"
ignore:
  - "*/codeql-packs/**/experimental/**/qlpack.yml"

registries:
 - packages: 'codeql/*'
   url: https://ghcr.io/v2/

 - packages: '*'
   url: https://containers.GHE_HOSTNAME/v2/

Para comprobar que el archivo codeql-workspace.yml incluye los paquetes de CodeQL que esperas, ejecuta el comando codeql pack ls en el mismo directorio que el área de trabajo. El resultado del comando es una lista de todos los paquetes de CodeQL en el área de trabajo.

Dependencias de origen

Las dependencias de origen son paquetes de CodeQL que se resuelven desde el sistema de archivos local fuera de la caché del paquete de CodeQL. Estas dependencias pueden estar en la mismo área de trabajo de CodeQL o especificarse como una opción de ruta de acceso mediante el argumento --additional-packs. Al compilar y ejecutar consultas localmente, las dependencias de origen invalidan las dependencias que se encuentran en la caché del paquete de CodeQL, así como las restricciones de versión definidas en qlpack.yml. Todas las referencias a los paquetes de CodeQL en la misma área de trabajo se resuelven como dependencias de origen.

Esto es especialmente útil en las situaciones siguientes:

• Una de las dependencias del paquete de consultas que estás ejecutando aún no está publicada. La resolución desde el origen es la única manera de hacer referencia a ese paquete.

• Estás realizando cambios en varios paquetes al mismo tiempo y quieres probarlos juntos. La resolución desde el origen garantiza que usas la versión del paquete con los cambios que contiene.

Áreas de trabajo y resolución de consultas de CodeQL

Todos los paquetes de CodeQL de un área de trabajo están disponibles como dependencias de origen entre sí al ejecutar cualquier comando de CodeQL que resuelva consultas o paquetes. Por ejemplo, cuando se ejecuta codeql pack install en un directorio del paquete de un área de trabajo, se usará cualquier dependencia que se pueda encontrar en el área de trabajo en lugar de descargar esa dependencia en la caché del paquete y agregarla al archivo codeql-pack.lock.yml. Para obtener más información, vea «Creación y uso de paquetes de CodeQL».

Del mismo modo, al publicar un paquete de consultas de CodeQL en el registro de contenedor de GitHub mediante codeql pack publish, el comando siempre usará las dependencias del área de trabajo en lugar de usar las que se encuentran en la caché del paquete local.

Esto garantiza que los cambios locales que realices en una biblioteca de consultas de una dependencia se reflejen automáticamente en los paquetes de consultas que publiques desde esa área de trabajo.

Ejemplo

Fíjese en el siguiente archivo codeql-workspace.yml :

provide:
  - "**/qlpack.yml"

Y el archivo qlpack.yml siguiente del paquete de bibliotecas de CodeQL en el área de trabajo:

name: my-company/my-library
library: true
version: 1.0.0

Y el archivo qlpack.yml siguiente del paquete de consultas de CodeQL en el área de trabajo:

name: my-company/my-queries
version: 1.0.0
dependencies:
  my-company/my-library: "*"
  codeql/cpp-all: ~0.2.0

Observe que en el bloque dependencies del paquete de consultas de CodeQL, my-company/my-queries, especifica "*" como la versión del paquete de bibliotecas. Puesto que el paquete de bibliotecas ya está definido como una dependencia de origen en codeql-workspace.yml, el contenido del paquete de bibliotecas siempre se resuelve desde dentro del área de trabajo. En este caso, se omitirá cualquier restricción de versión que defina. Se recomienda usar "*" para las dependencias de origen a fin de que quede claro que la versión se hereda del área de trabajo.

Cuando se ejecuta codeql pack install desde el directorio del paquete de consultas, se descarga una versión adecuada de codeql/cpp-all en la caché del paquete local. Además, se crea un archivo codeql-pack.lock.yml que contiene la versión resuelta de codeql/cpp-all. El archivo de bloqueo no contendrá una entrada para my-company/my-library, ya que se resuelve desde dependencias de origen. El archivo codeql-pack.lock.yml tendrá un aspecto similar al siguiente:

dependencies:
  codeql/cpp-all:
    version: 0.2.2

Cuando se ejecuta codeql pack publish desde el directorio del paquete de consultas, la dependencia codeql/cpp-all de la caché del paquete y el elemento my-company/my-library del área de trabajo se agrupan con my-company/my-queries y se publican en el registro de contenedor de GitHub.

Uso de ${workspace} como intervalo de versiones en archivos qlpack.yml

CodeQL paquetes de un área de trabajo pueden usar los marcadores de posición de intervalo de versiones especiales ${workspace}, ~${workspace} y ^${workspace}. Estos marcadores de posición indican que este paquete depende de la versión del paquete especificado que se encuentra actualmente en el área de trabajo. Este marcador de posición se usa normalmente para las dependencias dentro de los paquetes de biblioteca para asegurarse de que, cuando se publican, las dependencias de su archivo qlpack.yml reflejan el estado del área de trabajo cuando se publicaron.

Ejemplo

Ten en cuenta los dos paquetes de biblioteca siguientes en la misma área de trabajo:

name: my-company/my-library
library: true
version: 1.2.3
dependencies:
  my-company/my-library2: ${workspace}

name: my-company/my-library2
library: true
version: 4.5.6

Cuando my-company/my-library se publica en el registro de contenedor GitHub, la versión de la dependencia my-company/my-library2 en el archivo publicado qlpack.yml se escribirá como 4.5.6.

Del mismo modo, si la dependencia está my-company/my-library2: ^${workspace} en el paquete de origen y, a continuación, se publica el paquete, la versión de la dependencia my-company/my-library2 en el archivo qlpack.yml publicado se escribirá como ^4.5.6, lo que indica que las versiones >= 4.5.6 y < 5.0.0 son todas compatibles con este paquete de biblioteca.

Si la dependencia está my-company/my-library2: ~${workspace} en el paquete de origen y, a continuación, se publica el paquete, la versión de la dependencia my-company/my-library2 en el archivo qlpack.yml publicado se escribirá como ~4.5.6, lo que indica que las versiones >= 4.5.6 y < 4.6.0 son todas compatibles con este paquete de biblioteca.