About default setup
Default setup for code scanning is the quickest, easiest, most low-maintenance way to enable code scanning for your repository. Based on the code in your repository, default setup will automatically create a custom code scanning configuration. After enabling default setup, the code written in CodeQL-supported languages in your repository will be scanned:
- On each push to the repository's default branch, or any protected branch. For more information on protected branches, see "About protected branches."
- When creating or committing to a pull request based against the repository's default branch, or any protected branch, excluding pull requests from forks.
- On a weekly schedule.
Note
If no pushes and pull requests have occurred in a repository with default setup enabled for 6 months, the weekly schedule will be disabled to save your GitHub Actions minutes.
You can also enable default setup for multiple or all repositories in an organization at the same time. For information on bulk enablement, see "Configuring default setup for code scanning at scale."
If you need more granular control over your code scanning configuration, you should instead configure advanced setup. For more information, see "Configuring advanced setup for code scanning."
Requirements for using default setup
Your repository is eligible for default setup for code scanning if:
- GitHub Actions are enabled.
- It is publicly visible, or GitHub Advanced Security is enabled.
We recommend enabling default setup for eligible repositories if there is any chance the repositories will include at least one CodeQL-supported language in the future. If you enable default setup on a repository that does not include any CodeQL-supported languages, default setup will not run any scans or use any GitHub Actions minutes. If CodeQL-supported languages are added to the repository, default setup will automatically begin scanning CodeQL-supported languages and using GitHub Actions minutes. For more information on CodeQL-supported languages, see "About code scanning with CodeQL."
You can use default setup for all CodeQL-supported languages for self-hosted runners or GitHub-hosted runners. See "Assigning labels to runners", later in this article.
Default setup uses the none
build mode for C# and Java and uses the autobuild
build mode for other compiled languages. You should configure your self-hosted runners to make sure they can run all the necessary commands for C/C++, C#, and Swift analysis. Analysis of JavaScript/TypeScript, Go, Ruby, Python, and Kotlin code does not currently require special configuration.
Customizing default setup
We recommend that you start using code scanning with default setup. After you've initially configured default setup, you can evaluate code scanning to see how it's working for you. If you find that something isn't working as you expect, you can customize default setup to better meet your code security needs. For more information, see "Evaluating default setup for code scanning."
Configuring default setup for a repository
When you initially configure default setup for code scanning for a repository, all CodeQL-supported languages in the repository will be analyzed automatically. The languages that are analyzed successfully will be retained in the new default setup configuration. Languages that are not analyzed successfully will be automatically deselected from the default setup configuration.
Note
If the analyses fail for all CodeQL-supported languages in a repository, default setup will still be enabled, but it will not run any scans or use any GitHub Actions minutes until another CodeQL-supported language is added to the repository or default setup is manually reconfigured, and the analysis of a CodeQL-supported language succeeds.
-
On GitHub, navigate to the main page of the repository.
Note
If you are configuring default setup on a fork, you must first enable GitHub Actions. To enable GitHub Actions, under your repository name, click Actions, then click I understand my workflows, go ahead and enable them. Be aware that this will enable all existing workflows on your fork.
-
Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.
-
In the "Security" section of the sidebar, click Code security.
-
In the "Code scanning" section, select Set up , then click Default.
You will then see a "CodeQL default configuration" dialog summarizing the code scanning configuration automatically created by default setup.
- Optionally, in the "Query suites" section of the "CodeQL default configuration" modal dialog, select the Default dropdown menu, then click the CodeQL query suite you would like to use.
If you choose the Extended query suite, your code scanning configuration will run lower severity and precision queries in addition to the queries included in the Default query suite. For more information on the available query suites, see "CodeQL query suites."
Note
If you configure code scanning to use the Extended query suite, you may experience a higher rate of false positive alerts.
-
Optionally, to use labeled runners, in the "Runner type" section, select Standard GitHub runner then select Labeled runner. Then, next to "Runner label", enter the label of an existing self-hosted or GitHub-hosted runner. See "Assigning labels to runners", later in this article.
-
Review the settings for default setup on your repository, then click Enable CodeQL. This will trigger a workflow that tests the new, automatically generated configuration.
Note
If you are switching to default setup from advanced setup, you will see a warning informing you that default setup will override existing code scanning configurations. This warning means default setup will disable the existing workflow file and block any CodeQL analysis API uploads.
-
Optionally, to view your default setup configuration after enablement, select , then click View CodeQL configuration.
Assigning labels to runners
Note
Code scanning sees assigned runners when default setup is enabled. If a runner is assigned to a repository that is already running default setup, you must disable and re-enable default setup to start using the runner. If you add a runner and want to start using it, you can change the configuration manually without needing to disable and re-enable default setup.
You can also assign self-hosted runners with the default code-scanning
label, or you can optionally give them custom labels so that individual repositories can use different runners. For information about assigning labels to self-hosted runners, see "Using labels with self-hosted runners."
Specifying custom labels for self-hosted runners is optional. Unless you have a specific use case, we recommend that you only assign runners with the default code-scanning
label. For example, you may want to:
- Assign more powerful self-hosted runners to critical repositories for faster code scanning analysis.
- Run your code scanning analyses on a particular platform (for example, macOS).
- Have granular control over the workload for your GitHub-hosted runners and self-hosted runners.
Once you've assigned custom labels to self-hosted runners, your repositories can use those runners for code scanning default setup. For more information, see "Configuring default setup for a repository", earlier in this article.
You can also use security configurations to assign labels to self-hosted runners for code scanning. See "Creating a custom security configuration."
Assigning larger runners
To assign a larger runner, name the runner code-scanning
. This will automatically add the code-scanning
label to the larger runner. An organization can only have one larger runner with the code-scanning
label, and that runner will handle all code scanning jobs from repositories within your organization with access to the runner's group. See "Configuring larger runners for default setup."
Next steps
After your configuration runs successfully at least once, you can start examining and resolving code scanning alerts. For more information on code scanning alerts, see "About code scanning alerts" and "Assessing code scanning alerts for your repository."
After you've configured default setup for code scanning, you can read about evaluating how it's working for you and the next steps you can take to customize it. For more information, see "Evaluating default setup for code scanning."
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."
When you configure default setup, you may encounter an error. For information on troubleshooting specific errors, see "Troubleshooting code scanning."