{"id":15048256,"url":"https://github.com/github/codeql-learninglab-actions","last_synced_at":"2025-10-04T08:31:07.880Z","repository":{"id":40729770,"uuid":"229434737","full_name":"github/codeql-learninglab-actions","owner":"github","description":"Actions and Images for use in Learning Lab courses for CodeQL","archived":true,"fork":false,"pushed_at":"2022-08-18T19:20:17.000Z","size":278,"stargazers_count":35,"open_issues_count":5,"forks_count":23,"subscribers_count":285,"default_branch":"master","last_synced_at":"2025-01-16T09:25:41.903Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/github.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-21T13:56:20.000Z","updated_at":"2024-12-24T19:54:53.000Z","dependencies_parsed_at":"2022-07-21T00:54:15.927Z","dependency_job_id":null,"html_url":"https://github.com/github/codeql-learninglab-actions","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcodeql-learninglab-actions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcodeql-learninglab-actions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcodeql-learninglab-actions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/github%2Fcodeql-learninglab-actions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/github","download_url":"https://codeload.github.com/github/codeql-learninglab-actions/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235232437,"owners_count":18957056,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-09-24T21:09:53.012Z","updated_at":"2025-10-04T08:31:02.494Z","avatar_url":"https://github.com/github.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Actions for Learning Lab CodeQL Courses\n\n[![](https://github.com/github/codeql-learninglab-actions/workflows/CI/badge.svg)](https://github.com/github/codeql-learninglab-actions/actions?query=workflow%3ACI)\n[![](https://github.com/github/codeql-learninglab-actions/workflows/Build%20and%20publish%20docker%20images%20to%20registry/badge.svg)](https://github.com/github/codeql-learninglab-actions/actions?query=workflow%3A%22Build+and+publish+docker+images+to+registry%22)\n\nThis repository provides Docker images and GitHub Actions\nfor use in CodeQL courses\non [Learning Lab](https://lab.github.com/).\n\nThese actions allow you to specify workflows\nthat can check that course participants' queries are correct,\nby running their queries against a well-known CodeQL database,\nand checking the results are as expected.\nWhatever the outcome,\nthe action will post a comment on the commit which was pushed\nto add the queries.\n\nWhen a user's results are incorrect,\nthe comment will include details of which results are missing,\nand which are superfluous,\nincluding links to the lines of source code on GitHub when possible:\n\n**Screenshot:**\n\n![](docs/comment_screenshot.png)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**\n\n- [Creating your own course](#creating-your-own-course)\n  - [Creating the Query Checking Action](#creating-the-query-checking-action)\n    - [Testing the action](#testing-the-action)\n    - [Adding new queries \u0026 calculating the contents for the CSV files](#adding-new-queries--calculating-the-contents-for-the-csv-files)\n    - [Publishing your action](#publishing-your-action)\n  - [Contributing your GitHub Action to this repository](#contributing-your-github-action-to-this-repository)\n  - [Creating the Learning Lab Course](#creating-the-learning-lab-course)\n- [Example Courses](#example-courses)\n- [Contributing](#contributing)\n  - [Releasing new versions or updating dependencies](#releasing-new-versions-or-updating-dependencies)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Creating your own course\n\nThere are two main components to any Learning Lab course for CodeQL that uses\nthe components in this repository:\n\n* [**Query Checking Action:**](#creating-the-query-checking-action)\n\n  Each course has its own GitHub Action that is designed to be used in workflows\n  that run when a course participant pushes new commits to their repo.\n  The action will check which queries have changed in the push,\n  and run the queries that it recognizes as part of the course\n  (based on the filename).\n\n  After running the queries,\n  the action will check the results against a CSV file of expected results.\n  It will then post a comment on the commit,\n  detailing whether each query produced the correct results or not.\n  And if not,\n  it will include details of which results are missing,\n  and which results are unexpected.\n\n  These actions are bundled using Docker,\n  and made available using\n  [GitHub Packages](https://github.com/features/packages).\n\n* [**Learning Lab Course:**](#creating-the-learning-lab-course)\n\n  This is the course itself.\n  It creates the initial repository the participant will use for their course,\n  posts instructions as GitHub issues,\n  and listens for comments posted by the GitHub action to know when the user\n  has completed the current task correctly,\n  and is ready to advance to the next one.\n\n### Creating the Query Checking Action\n\n*(for an example of a working action,\nsee [`courses/cpp/ctf-segv`](courses/cpp/ctf-segv)).*\n\nCourse actions consist of an `action.yml` file,\nand docker image built from the base image\n[`codeql-learninglab-check`](codeql-learninglab-check).\n\nThe base image expects course images built on-top of it\nto add the file `/home/codeql/config/config.json`,\nwhich details the configuration for the course.\n\nThe file should look something like this:\n\n```json\n{\n  \"databasePath\": \"\u003cpath-to-database-directory\u003e\",\n  \"locationPaths\": \"https://github.com/\u003cowner\u003e/\u003crepo\u003e/blob/\u003csha\u003e{path}#L{line-start}-L{line-end}\",\n  \"expectedResults\": {\n    \"step-01.ql\": \"step-01.csv\",\n    \"step-02.ql\": \"step-02.csv\",\n    \"step-03.ql\": false,\n  }\n}\n```\n\nIn addition to the `config.json` file above,\na course image needs to also add the snapshot directory\nthat queries should be run against,\nand csv files for the expected results.\n\n* `databasePath` should be a directory in the docker image,\n  relative to the `config.json` file,\n  that contains the extracted CodeQL database that queries will be run against.\n  If you are using the template below,\n  it will usually be the name of the only top-level directory\n  from inside the database zip file.\n* `locationPaths` is an optional template string that can be used to enable\n  source links in comments, when participants have written queries that output\n  unexpected rows, or are missing results.\n  `\u003cowner\u003e`, `\u003crepo\u003e` and `\u003csha\u003e` should be replace as appropriate,\n  the placeholders `{path}`, `{line-start}` and `{line-end}` are used by the\n  checker, and should be left as-is.\n* `expectedResults` is an object that maps expected query filenames to a csv\n  file detailing what the expected results for this query should be.\n  Only the first expression for each row in the query results is checked.\n  If instead of a CSV filename, `false` is used,\n  then the checker will assume that the CSV file has simply\n  never been generated,\n  and will print out the resulting output from the query for you to copy into a\n  new file.\n\n\nTo simplify course creation,\nwe recommend structuring your course folder like so:\n\n```\n├── answers               \u003c─── Model Answers\n│   ├── qlpack.yml\n│   ├── step-01.ql        \u003c─┬─ Answers with expected paths\n│   ├── step-02.ql        \u003c─┤  (relative to answers/)\n│   └── ...               \u003c─┘  as specified in config.json\n├── image\n│   ├── config\n│   │   ├── config.json   \u003c─── Main course configuration\n│   │   ├── step-01.csv\n│   │   ├── step-02.csv\n│   │   └── ...\n│   └── Dockerfile\n└── action.yml\n```\n\n*(For your convinience,\nwe've created a template course that uses this file-structure\nin the folder [`templates/action`](templates/action).\nYou can simply copy the folder,\nand follow the instructions in the template README for what things to replace).*\n\n`action.yml` should look something like this:\n\n```yml\nname: 'Check queries'\ndescription: 'Check that the queries that have been pushed (as part of the lesson) produce the correct results'\nauthor: 'GitHub \u003copensource+codeql-learninglab-actions@github.com\u003e'\nruns:\n  using: 'docker'\n  image: 'docker://docker.pkg.github.com/\u003cowner\u003e/\u003crepo\u003e/\u003cpackage\u003e'\nbranding:\n  icon: 'check-circle'\n  color: 'purple'\n```\n\nand `Dockerfile` should look something like:\n\n```Dockerfile\nFROM docker.pkg.github.com/github/codeql-learninglab-actions/codeql-learninglab-check:\u003cversion\u003e\n\n## Add course config\nCOPY --chown=codeql:codeql config /home/codeql/config\nWORKDIR /home/codeql/config\n# Download, unzip and then delete the zip file in one step to reduce image size\nRUN wget --quiet \u003curl-for-snapshot-zip\u003e -O database.zip \u0026\u0026 unzip -qq database.zip \u0026\u0026 rm -rf database.zip\n```\n\nNote that we download, unzip and then delete the zip file of the snapshot\nin a single step here.\nThis helps us reduce the size of the image,\nas separate steps would result in intermediate image layers that are built\non-top of one another.\n\n#### Testing the action\n\nYou can test the action either locally or on GitHub actions.\n\n**Locally:**\n\nTo test a course locally,\nfrom the course directory,\nrun either of these scripts:\n\n* [`scripts/test-course-actual.sh`](scripts/test-course-actual.sh):\n  which will download and use the specific version of `codeql-learninglab-check`\n  that is specified in `Dockerfile`\n* [`scripts/test-course-latest.sh`](scripts/test-course-latest.sh):\n  Which will also build the `codeql-learninglab-check` image locally,\n  and tag it with the expected base image of the course,\n  allowing you to test how changes to the `codeql-learninglab-check`\n  affect this specific course,\n  without publishing any new images.\n\nBoth scripts take as argument an **optional** regexp string.\nIf this string is passed, only the queries \nwith names matching the regexp will be run.\nOtherwise all queries are run.\n\n**In GitHub Actions:**\n\nIf adding a course to this repository,\nextend the workflow file [`.github/workflows/ci.yml`](.github/workflows/ci.yml)\nto include your new course.\nAny subsequent pushes to any branch should trigger an Action to run\nthat will succeed only when all the expected queries produce the right results.\n\nIf you are creating a course in another repository,\nyou can copy the [`scripts/test-course-actual.sh`](scripts/test-course-actual.sh)\nand [`scripts/test-course-latest.sh`](scripts/test-course-latest.sh) files\ninto that repository,\nand add a similar workflow file to the one mentioned above.\n\n#### Adding new queries \u0026 calculating the contents for the CSV files\n\nWhen testing the action ([as detailed above](#testing-the-action)),\nwhen a query that is run produces unexpected results,\nor it is specified as `false` in `config.yml` instead of listing a CSV filename,\nthe actual results that it produces are printed out in the console.\nYou can then store this output as the relevant CSV file.\n\nSo the workflow for adding a new query and CSV file looks like:\n\n* add the query (`.ql` file) to `answers/`.\n* add the query to the `expectedResults` property in `config.json`,\n  with a starting value of `false`.\n* Test the action (whichever method you prefer).\n* Copy the CSV output to the appropriate file in `image/config/`.\n* Re-test the action to ensure it marks the query\n  as producing the correct results.\n\n#### Publishing your action\n\nThe main thing you need to do here is publish your Docker image somewhere,\nand ensure that `action.yml` referrs to a tag that is downloadable.\n\nWe recommend setting up a GitHub Actions Workflow\nto automatically publish your docker image\nwith the version `latest` to `docker.pkg.github.com`\nwhenever you get a new push to `master`.\nThis is what we do in\n[`.github/workflows/publish.yml`](.github/workflows/publish.yml).\n\nAny courses that are added to this repository\nneed to be published in this manner.\n\n### Contributing your GitHub Action to this repository\n\nIf you want to add a course to this repository,\nensure that:\n\n* You're creating the course in the `courses/` folder,\n  under the appropriate language sub-folder for the project.\n* You update both [`.github/workflows/ci.yml`](.github/workflows/ci.yml) and\n  [`.github/workflows/publish.yml`](.github/workflows/publish.yml) to include\n  testing and image publishing for your course.\n\n### Creating the Learning Lab Course\n\nIf you have not created a Learning Lab course before,\nit is recommended to take the\n[course on creating a course](https://lab.github.com/githubtraining/write-a-learning-lab-course)!\n\nThere are core repositories that need to be created as part of any learning-lab\ncourse:\n\n* **The course repository:**\n  All the course configuration, instructions etc...\n* **The template repository:**\n  The initial contents that populate the repository\n  created on behalf of the course participant.\n  (All courses are taken with respect to it's own repository)\n\nWe've created two template directories\nthat you can use as a starting point for your own CodeQL Learning Lab Course:\n\n* [`templates/learninglab/course`](templates/learninglab/course)\n* [`templates/learninglab/course-template`](templates/learninglab/course-template)\n\nSimply copy the contents of these templates into their own repositories,\nand follow the [template instructions](templates/learninglab) to get started.\n\n*(Remember that you need to create 2 separate repositories\nfor your Learning Lab course,\nthey can't be directories in an existing repo).*\n\n## Example Courses\n\n* [GitHub Security Lab CTF 1: SEGV hunt](courses/cpp/ctf-segv)\n\nFeel free to add your own courses to this list!\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Contributing\n\nWe welcome contributions,\nboth for new courses,\nand improvements to existing courses ot the\n[`codeql-learninglab-check`](codeql-learninglab-check) docker image.\n\n### Releasing new versions or updating dependencies\n\nSee: [Updating and Releasing](CONTRIBUTING.md#updating-and-releasing)\n\n## License\n\nThe code in this repository is licensed under MIT (see [LICENSE.md](LICENSE.md)).\nHowever as it makes use of the CodeQL CLI,\nyou must also abide by the\n[GitHub CodeQL Terms and Conditions](https://securitylab.github.com/tools/codeql/license),\nwhenever your usage involves the CodeQL CLI.\n\nIn particular,\nyou are not permitted to use these docker images or actions\nto create CodeQL databases using the CLI in CI/CD,\nas per the [terms \u0026 conditions](https://securitylab.github.com/tools/codeql/license):\n\n\u003e **the Software cannot be used** [...]\n\u003e **To generate CodeQL databases for or during automated analysis,\n\u003e continuous integration or continuous delivery,\n\u003e whether as part of normal software engineering processes or otherwise.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fcodeql-learninglab-actions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithub%2Fcodeql-learninglab-actions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithub%2Fcodeql-learninglab-actions/lists"}