How to Enable CodeQL Analysis in Your GitHub Repository

What is CodeQL?

CodeQL is GitHub's semantic code analysis engine that lets you discover vulnerabilities in your code before they reach production. It treats code as data, allowing you to query your codebase like a database and find security weaknesses automatically.

Why Use CodeQL?

Detect Real Vulnerabilities: Find SQL injections, XSS, path traversals, and more
Integrated Security: Runs directly in your GitHub workflow
Multiple Languages: Supports JavaScript, TypeScript, Python, Java, C#, C++, Go, and Ruby
Free for Public Repositories: Complete security analysis at no cost for open-source projects

Setting Up CodeQL Analysis in few Steps

Enable GitHub Actions in Your Repository

First, make sure GitHub Actions is enabled:

1. Navigate to your repository on GitHub
2. Click on the "Settings" tab
3. Select "Actions" from the sidebar
4. Make sure "Allow all actions and reusable workflows" is selected

First (easier) method

Go to your repository and click in Security Tab.

Now click on setup code scanning

Now select Default option

After select default you'll see the following prompt

• It shows languages that you have in your project and workflows if available too. You can click in edit to remove languages, workflows, select branchs to run and so forth.

Now the second way

Create a CodeQL Workflow File
Create a new file at .github/workflows/codeql-analysis.yml with the following content:

name: "CodeQL Analysis"

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]
  schedule:
    - cron: '30 1 * * 0'  # Runs at 1:30 AM UTC every Sunday

jobs:
  analyze:
    name: Analyze
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      security-events: write

    strategy:
      fail-fast: false
      matrix:
        language: [ 'javascript', 'python' ]  # Modify these languages as needed
        # Available options: 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby'

    steps:
    - name: Checkout repository
      uses: actions/checkout@v3

    - name: Initialize CodeQL
      uses: github/codeql-action/init@v2
      with:
        languages: ${{ matrix.language }}

    # Autobuild attempts to build any compiled languages
    - name: Autobuild
      uses: github/codeql-action/autobuild@v2

    - name: Perform CodeQL Analysis
      uses: github/codeql-action/analyze@v2
      with:
        category: "/language:${{matrix.language}}"

Customize for Your Project

Modify the workflow file based on your needs:

• Branches: Change main to your default branch name if different
• Languages: Update the language matrix to include only languages your project uses
• Schedule: Adjust the cron schedule as needed for regular scanning

Commit and Push Your Changes

git add .github/workflows/codeql-analysis.yml
git commit -m "Add CodeQL security scanning workflow"
git push

View Results in the Security Tab

After the workflow runs:

1. Go to your repository on GitHub
2. Click on the "Security" tab
3. Select "Code scanning alerts" from the left sidebar
4. Review any security vulnerabilities discovered by CodeQL

Code with some security alerts

Advanced Configuration

Custom Build Steps
If your project requires custom build steps instead of using the autobuild feature:

# Replace the autobuild step with custom commands
- name: Custom Build Steps
  run: |
    # Add your custom build commands here
    ./configure
    make bootstrap
    make release

- name: Perform CodeQL Analysis
  uses: github/codeql-action/analyze@v2
Adding CodeQL Query Suites
You can use custom query suites for specialized analysis:
yaml- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    languages: ${{ matrix.language }}
    queries: security-extended,security-and-quality

Available query suites include:

security-extended: Additional queries for security analysis
security-and-quality: Security queries plus quality and correctness

Troubleshooting

Common Issues

• Workflow not running

  • Check that GitHub Actions is enabled
  • Verify branch names match your repository

• Builds failing

  • Look at workflow logs to identify build issues
  • Consider using custom build steps if autobuild fails

• Memory issues

  • For large codebases, you might need to adjust RAM limits:

- name: Initialize CodeQL
  uses: github/codeql-action/init@v2
  with:
    languages: ${{ matrix.language }}
    ram: '8192'

Best Practices

1. Run on schedule to catch issues even when code isn't actively being pushed
2. Review alerts promptly and address security issues
3. Use pull request integration to catch issues before they're merged
4. Configure code owners for security alerts to ensure follow-up

Conclusion

Setting up CodeQL is a powerful step toward securing your codebase. By incorporating it into your GitHub workflow, you create an automated security review process that can catch vulnerabilities before they impact your users.
For more information, check GitHub's official CodeQL documentation.

Have you implemented CodeQL in your projects? Share your experience in the comments below!