Acerca de las áreas de trabajo de CodeQL

Acerca de las áreas de trabajo de CodeQL

Un área de trabajo de CodeQL se suele usar para desarrollar un conjunto de paquetes de biblioteca y consulta que dependen entre sí. 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. Para más información sobre paquetes de CodeQL, consulta Personalización del análisis con paquetes de CodeQL.

Las áreas de trabajo se almacenan normalmente en un único repositorio de Git para que los paquetes relacionados se puedan desarrollar y publicar juntos.

Dependencias de origen

En un área de trabajo de CodeQL, todos los paquetes incluidos en el área de trabajo se consideran dependencias de origen entre sí. Esto significa que se resuelven directamente desde el sistema de archivos local en lugar de desde la caché de paquetes CodeQL.

Dado que los paquetes de áreas de trabajo se resuelven desde el origen:

• Los cambios locales de un paquete son visibles inmediatamente para otros paquetes dentro del espacio de trabajo.
• Dependencias encontradas en el área de trabajo anulan las versiones en la memoria caché del paquete.
• Las restricciones de versión en los archivos qlpack.yml se omiten para las dependencias del área de trabajo, ya que la versión se determina por el contenido del área de trabajo.

Este comportamiento es especialmente útil al desarrollar varios paquetes relacionados al mismo tiempo. Por ejemplo:

• Todavía no se ha publicado una dependencia y está disponible solo de manera local.
• Está realizando cambios coordinados en varios paquetes y los necesita para resolverse entre sí durante las pruebas.

Fuera de un área de trabajo, las dependencias se resuelven desde la memoria caché del paquete y deben coincidir con las restricciones de versión definidas en qlpack.yml. Dentro de un área de trabajo, la resolución prioriza el contenido de origen local en su lugar.

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

El modelo de dependencia del área de trabajo afecta a cómo se instalan y publican los paquetes.

• Durante la instalación, las dependencias que se encuentran en el área de trabajo no se descargan en la memoria caché del paquete y no se escriben en el codeql-pack.lock.yml archivo.
• Durante la publicación, las dependencias proporcionadas por el área de trabajo se agrupan con su contenido de origen local en lugar de las versiones de la caché del paquete.

Por ejemplo, la ejecución codeql pack install en un directorio de paquete dentro de un área de trabajo usa las dependencias que se encuentran en el área de trabajo en lugar de descargarlas en la memoria caché del paquete o grabarlas en el codeql-pack.lock.yml archivo. Consulta Creación y uso de paquetes de CodeQL.

Example

Un área de trabajo CodeQL se define mediante un archivo YAML denominado codeql-workspace.yml. 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

Observa que en el bloque dependencies del paquete de consultas de CodeQL, my-company/my-queries, se 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. El uso de "*" para las dependencias de origen hace explícito 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.

Ejemplo de un codeql-workspace.yml archivo

Un área de trabajo CodeQL se define mediante un archivo YAML denominado codeql-workspace.yml. 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. Consulta 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/

Puede enumerar los paquetes incluidos en un área de trabajo mediante la ejecución codeql pack ls en el directorio del área de trabajo.

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 utiliza normalmente para dependencias en paquetes de bibliotecas, garantizando que, al publicarse, las dependencias en su archivo qlpack.yml reflejen el estado del espacio de trabajo en el momento de su publicación.

Example

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.