You can configure advanced setup for a repository to find security vulnerabilities in your code using a highly customizable code scanning configuration.
Who can use this feature?
Repository owners, organization owners, security managers, and users with the admin role
Code scanning is available for the following repository types:
Public repositories on GitHub.com
Organization-owned repositories on GitHub Team with GitHub Code Security enabled
Advanced setup for code scanning is helpful when you need to customize your code scanning. By creating and editing a workflow file, you can define how to build compiled languages, choose which queries to run, select the languages to scan, use a matrix build, and more. You also have access to all the options for controlling workflows, for example: changing the scan schedule, defining workflow triggers, specifying specialist runners to use. For more information about GitHub Actions workflows, see Workflows.
If you run code scanning using multiple configurations, an alert will sometimes have multiple analysis origins. If an alert has multiple analysis origins, you can view the status of the alert for each analysis origin on the alert page. For more information, see About code scanning alerts.
If you do not need a highly customizable code scanning configuration, consider using default setup for code scanning. For more information on eligibility for default setup, see Configuring default setup for code scanning.
You can customize your CodeQL analysis by creating and editing a workflow file. Selecting advanced setup generates a basic workflow file for you to customize using standard workflow syntax and specifying options for the CodeQL action. See Workflows and Customizing your advanced setup for code scanning.
Using actions to run code scanning will use minutes. For more information, see GitHub Actions billing.
Note
You can configure code scanning for any public repository where you have write access.
On GitHub, navigate to the main page of the repository.
Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.
In the "Security" section of the sidebar, click Advanced Security.
Scroll down to "Code Security", in the "CodeQL analysis" row select Set up , then click Advanced.
Note
If you are switching from default setup to advanced setup, in the "CodeQL analysis" row, select , then click Switch to advanced. In the pop-up window that appears, click Disable CodeQL.
Screenshot of the "Code Security" section of "Advanced Security" settings. The "Advanced setup" button is highlighted with an orange outline.
To customize how code scanning scans your code, edit the workflow.
Generally, you can commit the CodeQL analysis workflow without making any changes to it. However, many of the third-party workflows require additional configuration, so read the comments in the workflow before committing.
Click Commit changes... to display the commit changes form.
Screenshot of the form to create a new file. To the right of the file name, a green button, labeled "Commit changes...", is outlined in dark orange.
In the commit message field, type a commit message.
Choose whether you'd like to commit directly to the default branch, or create a new branch and start a pull request.
Click Commit new file to commit the workflow file to the default branch or click Propose new file to commit the file to a new branch.
If you created a new branch, click Create pull request and open a pull request to merge your change into the default branch.
In the suggested CodeQL analysis workflow, code scanning is configured to analyze your code each time you either push a change to the default branch or any protected branches, or raise a pull request against the default branch. As a result, code scanning will now commence.
GitHub includes workflow templates for third-party actions, as well as the CodeQL action. Using a workflow template is much easier than writing a workflow unaided.
Using actions to run code scanning will use minutes. For more information, see GitHub Actions billing.
On GitHub, navigate to the main page of the repository.
Under your repository name, click Actions.
Screenshot of the tabs for the "github/docs" repository. The "Actions" tab is highlighted with an orange outline.
If the repository has already at least one workflow configured and running, click New workflow to display workflow templates. If there are currently no workflows configured for the repository, go to the next step.
Screenshot of the Actions tab for a repository. The "New workflow" button is outlined in dark orange.
In the "Choose a workflow" or "Get started with GitHub Actions" view, scroll down to the "Security" category and click Configure under the workflow you want to configure. You may need to click View all to find the security workflow you want to configure.
Screenshot of the Security category of workflow templates. The Configure button and "View all" link are highlighted with an orange outline.
Follow any instructions in the workflow to customize it to your needs. For more general assistance about workflows, click Documentation on the right pane of the workflow page.
Screenshot showing a workflow template file open for editing. The "Documentation" button is highlighted with an orange outline.
When you have finished defining your configuration, add the new workflow to your default branch.
You can find detailed information about your code scanning configuration, including timestamps for each scan and the percentage of files scanned, on the tool status page. For more information, see About the tool status page for code scanning.