Before you start #
You need to have signed up — see Sign up. You also need at least one repository you have access to on GitHub or Bitbucket (public or private). GitLab support is on the roadmap; see Repository providers.
How to connect your first repository #
When you first sign in to a brand-new account, you land on a screen titled Let’s get your first repository analyzed. There are no other distractions on this page — no sidebar, no workspace selector — just the connection options.
1. Choose your provider #
Click one of the buttons:
- Connect GitHub
- Connect Bitbucket
GitLab connection isn’t available yet — see Repository providers for status.
You’ll be sent to the provider’s authorisation screen.
2. Authorise Norma #
The provider will ask which repositories Norma can read. We recommend giving access to only the repositories you want to scan — you can add more later.
Norma requests read access only. It cannot push, commit, or modify your code. See What Norma can see for the full list of permissions.
3. Pick the repository to analyse #
You’re back in Norma on the Select repository screen, which lists all repositories you authorised. For each one you see the name, organisation, URL, and provider badge.
- Use the search box at the top if you have many repositories.
- Click a repository to select it.
If the list is empty, you didn’t share any repositories during the authorisation step. Click Reconfigure access to go back to the provider and try again.
4. Confirm name and branch #
The next screen pre-fills:
- Name — taken from the repository’s name on the provider.
- Branch — the default branch is selected (
main,master, etc.).
You can override either before continuing. When ready, click Import & Analyze.
5. Watch Norma work #
After you click Import & Analyze, you don’t have to do anything else. Norma takes you to a guided progress page that shows five steps in real time:
- Importing your repository — connecting to the provider and downloading your code.
- Discovering your stack — detecting languages and frameworks. You’ll see each detection appear as it’s found.
- Stack confirmed — a short summary of what we found (e.g., TypeScript, React, FastAPI).
- Analyzing your codebase — running scanners across your code.
- Score ready — you’re automatically taken to the repository Overview, showing your Production Ready Score.
Total time: usually under five minutes for a typical repository.
You can click Skip — I’ll check results later at any point. The scan continues in the background and you’ll get a toast notification when it finishes.
What happens next #
Read Your first scan to understand what your Production Ready Score means and where to look first.
If something goes wrong #
- OAuth fails (“Could not connect to GitHub”): retry from the button. If it keeps failing, check that you didn’t revoke Norma on the provider’s side.
- No repositories show up: you didn’t grant access to any during the authorisation step. Click Reconfigure access on the empty list.
- Import fails: most often a permissions issue. The error message will say exactly which repo couldn’t be read. Re-authorise to fix.
- Discovery fails: rare — usually means we couldn’t find a recognised manifest file in your repo. You can click Continue to scan anyway to run the scan without an auto-detected stack profile.
- Scan fails: you’ll see a Retry scan button. If it fails twice, contact support — the error message includes a trace ID you can include in the report.
Related #
- Sign up — create the account that connects the repository.
- Your first scan — what to look at after the first scan completes.
- Repository providers — the full reference for GitHub, Bitbucket, and GitLab.
- Supported languages and frameworks — what Norma will scan.
