nRF Connect SDK code base

The source code, libraries, and tools that compose the nRF Connect SDK are entirely hosted in a set of Git repositories. Basic familiarity with Git is required to understand the architecture of the repository set and to work with the nRF Connect SDK.

All nRF Connect SDK repositories are publicly hosted on the nrfconnect GitHub organization, and accessible to both individual users and companies.

Repository types

There are two main types of Git repositories in the nRF Connect SDK repository set:

  • nRF repositories

    • Created, developed, and maintained by Nordic.

    • Usually licensed for use on Nordic products only.

  • OSS repositories

    • Created and maintained by Nordic.

    • Soft forks of open-source projects.

    • Typically contain a small set of changes that are specific to nRF Connect SDK.

    • Updated (“upmerged”) regularly with the latest changes from the open source project.

nRF repositories are stand-alone and have no upstreams, since they are unique to the nRF Connect SDK. Some examples of repositories of this type are:

  • sdk-nrf: The main repository for Nordic-developed software.

  • sdk-nrfxlib: A repository containing linkable libraries developed by Nordic.

OSS repositories, on the other hand, are typically soft forks of an upstream open source project, which Nordic maintains in order to keep a small set of changes that do not belong, or have not been merged, to the upstream official open-source repository. For example:

Repository structure

The nRF Connect SDK uses west to manage the combination of repositories and versions.

A manifest repository, sdk-nrf, contains a file in its root folder, west.yml, which lists all other repositories (west projects) included in the nRF Connect SDK. The nRF Connect SDK repository structure has a star topology, with the sdk-nrf repository being the center of the star and all other repositories being west projects that are managed by west.yml. This is equivalent to topology T2 in the west documentation.

A graphical depiction of the |NCS| repository structure

The nRF Connect SDK repository structure

The figure above depicts the nRF Connect SDK repository structure. A central concept with this repository structure is that each revision (in Git terms) of the sdk-nrf repository completely determines the revisions of all other repositories (that is, the west projects). This means that the linear Git history of this manifest repository also determines the history of the repository set in its entirety, thanks to the west.yml west manifest file being part of the manifest repository. West reads the contents of the manifest file to find out which revisions of the project repositories are to be checked out every time west update is run. In this way, you can decide to work with a specific nRF Connect SDK release either by initializing a new west installation at a particular tag or by checking out the corresponding tag for a release in an existing installation and then updating your project repositories to the corresponding state with west update. Alternatively, you can work with the latest state of development by using the main branch of the sdk-nrf repository, updating it with Git regularly and using west update to update the project repositories every time the manifest repository changes. More information about manifests can be found in the west manifest section of the Zephyr documentation.

Versions and revisions

The nRF Connect SDK version numbers are assigned based on very specific criteria. They follow the MAJOR.MINOR.PATCH pattern (also further called as X.Y.Z), with possible additional postfixes depending on the release.

Release type

Release critera



Introduces a large number of substantial changes across the board

Major version number is increased rarely and the release is accompanied by a migration guide.


Introduces one or more new functionalities.

Version number is increased every time a major release is cut. Minor releases are the default types of an nRF Connect SDK release. The new functionalities may break exisiting APIs.


Introduces bugfixes or minor changes to the existing functionalities.

Patch releases only address functional issues and do not introduce new functionalities.


The 99 added at the end of the version number indicates that the version string is a point in between two releases. Such version does not belong to a release and corresponds to the current state of development.

The number can be used between minor, major, or patch releases.


Development tag, marked through a postfix added to the end of the version. Indicates a snapshot of the development state that is created to highlight the introduction of a new piece of functionality.

-devN version might not be subjected to the same amount of testing as the nRF Connect SDK release.

There are two fundamental revisions that are relevant to most nRF Connect SDK users:

  • The main branch of the sdk-nrf repository

  • Any Git tag (that is, release, release candidate or development tag) of the sdk-nrf repository

The main branch of the sdk-nrf repository always contains the latest development state of the nRF Connect SDK (MAJOR.MINOR.99). Since all development is done openly, you can use it if you are not particularly concerned about the stability and want to track the latest changes that are being merged continuously into different repositories.

The nRF Connect SDK revision entry changes every time a Git commit is merged into the sdk-nrf repository. The revision of the SDK is considered to be equivalent to the repository revision of sdk-nrf, because it is the manifest repository. This means that, by virtue of containing the west manifest file, its revision uniquely identifies the revisions of all other repositories included in the SDK.

Git tags

The Git tags correspond to official releases tested and signed by the Nordic engineers. The format for nRF repositories is as follows:


Where X, Y and Z are the MAJOR, MINOR and PATCH version respectively. A release candidate postfix -rcN can be optionally attached if the tag identifies a candidate instead of the actual release.

The Git tags are composed as follows:


Tags without a suffix correspond to official releases tested and signed by Nordic Semiconductor engineers. A release candidate suffix -rcN is attached if the tag identifies a candidate instead of the actual release.

In between releases, there might be development tags. These are identified by a -devN suffix included after the nRF Connect SDK version, for example v1.9.99-dev1 for the main branch or v1.9.2-dev1 for the release branch. Such versions indicate a snapshot of the development state that is created to highlight the introduction of a new piece of functionality. Unlike an nRF Connect SDK release, a -devN version may or may not have received the same amount of testing.

In the case of OSS repositories, the git tag format reuses the upstream project’s version along with some nRF Connect SDK specific postfixes:


In this format, X, Y and Z are the MAJOR, MINOR and PATCH versions of the upstream project, and -ncsN is used to identify the number of nRF Connect SDK releases based on that particular version.

OSS repositories downstream project history

As described in Repository types, the nRF Connect SDK contains OSS repositories, which are based on third-party, open-source Git repositories and may contain additional patches not present upstream. Examples include sdk-zephyr and sdk-mcuboot, which have upstream open-source projects used as a basis for downstream repositories distributed with the nRF Connect SDK. This section describes how the history of these OSS repositories is maintained, and how they are synchronized with their upstreams.

The short logs for these downstream patches contain [nrf xyz] at the beginning, for different xyz strings. This makes their different purposes downstream clearer, and makes them easier to search for and see in git log. The current values of [nrf xyz] are:

  • [nrf mergeup]- Periodic merges of the upstream tree

  • [nrf fromlist]- Patches which have upstream pull requests, including any later revisions

  • [nrf noup]- Patches which are specific to the nRF Connect SDK

  • [nrf fromtree]- Patches which have been cherry-picked from an upstream tree


The downstream project history is periodically rewritten. This is important to prevent the number of downstream patches included in a specific nRF Connect SDK release from increasing forever. A repository’s history is typically only rewritten once for every nRF Connect SDK release.

To make incorporating new history into your own forks easier, a new point in the downstream nRF Connect SDK history is always created which has an empty git diff with the previous version. The empty diff means you can always use:

  • git merge to get the rewritten history merged into your own fork without errors

  • git rebase --onto or git cherry-pick to reapply any of your own patches cleanly before and after the history rewrite

  • git cherry to list any additional patches you may have applied to these projects to rewrite history as needed

Additionally, both the old and new histories are committed sequentially into the revision fields for these projects in the nrf/west.yml west manifest file. This means you can always combine git bisect in the nrf repository with west update at each bisection point to diagnose regressions and the rest.

Userdata associated with OSS repositories

The west manifest file nrf/west.yml contains userdata values for some OSS repository projects.

This section documents these values and their purpose. However, they are mainly meant for internal use and are safe to ignore.

See Repository user data for general information about the west userdata feature.

In the nRF Connect SDK, each userdata value has this format:

  upstream-url: https://...
  upstream-sha: GIT_SHA
  compare-by-default: <true|false>

These fields are used to track some extra OSS repository metadata. The metadata is present for projects which are not included in the nRF Connect SDK directly from the Zephyr project’s manifest in zephyr/west.yml. Repository maintainers use this metadata while synchronizing the nRF Connect SDK fork of each repository with its upstream repository.

The meaning of each userdata field is:

  • upstream-url - Git URL that the project is synchronized against

  • upstream-sha - Most recent Git SHA in the upstream-url repository which is included in the nRF Connect SDK fork of the repository

  • compare-by-default - If true, internal nRF Connect SDK synchronization tooling will include information related to this repository by default