Connect GitHub CODEOWNERS with Repository, Team & User

This guide demonstrates how to map CODEOWNERS files in GitHub to their respective repositories, teams and users in Port using the built-in User and Team blueprints.

Available Github Integrations

This guide includes steps that require integration with GitHub:

• GitHub (Ocean) - uses the Ocean framework. We strongly recommend this integration for new and migrated setups.
• GitHub (Sunset) - uses a GitHub app that is in sunset and will be fully deprecated on September 15, 2026.

Prerequisites

• A Port account.

GitHub (Ocean)

• Install GitHub Ocean.

Default GitHub blueprints

Once you install GitHub Ocean, the following blueprints will be automatically created in your data model: Repository, Pull Request, Github User, Github Team.

GitHub (Sunset)

• Install Port's GitHub app in your organization or in repositories you are interested in.

Default GitHub blueprints

Once you install Port's GitHub app, the following blueprints will be automatically created in your data model: Repository, Pull Request, Github User, Github Team.

Set up data model

First, let's create the necessary blueprint to store the Codeowners data, then we will set up the mapping configuration.

Create the Codeowners blueprint

To add the CODEOWNERS blueprint:

1. Navigate to your data model page of your portal.

2. Click on the + Blueprint button.

3. Click on the Edit JSON button.

4. Copy the following definition and paste it in the editor, then click Save:

   CODEOWNERS blueprint (Click to expand)

   {
     "identifier": "githubCodeowners",
     "description": "This blueprint represents a CODEOWNERS file in a service",
     "title": "Github Codeowners",
     "icon": "Github",
     "schema": {
       "properties": {
         "location": {
           "type": "string",
           "title": "File location",
           "description": "File path to CODEOWNERS file"
         },
         "scope": {
           "icon": "DefaultProperty",
           "type": "string",
           "title": "Scope",
           "description": "The scope which the user/team owns."
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "aggregationProperties": {},
     "relations": {
       "users": {
         "title": "Users",
         "target": "_user",
         "required": false,
         "many": true
       },
       "teams": {
         "title": "Teams",
         "target": "_team",
         "required": false,
         "many": true
       },
       "repository": {
         "title": "Repository",
         "description": "The repository which the CODEOWNERS file resides in",
         "target": "githubRepository",
         "required": true,
         "many": false
       }
     }
   }

Set up mapping configuration

GitHub (Ocean)

1. Go to the data sources page of your portal.

2. Under Exporters, click on your installed GitHub ocean integration.

3. A window will open containing the default YAML configuration of your GitHub ocean integration.

4. In the bottom-left corner you can modify the configuration to suit your needs, by adding/removing entries.

5. Copy the following configuration and paste it in the editor, then click Save & Resync:

   CODEOWNERS mapping configuration (Click to expand)

   resources:
     - kind: file
       selector:
         query: .repository.archived == false
         files:
           - path: '**/.github/CODEOWNERS'
             organization: my-org  # Optional if githubOrganization is set (required if not set)
             # repos:  # Optional: omit to scan all repos
             #   - name: my-repo
             #     branch: main
       port:
         itemsToParse: >-
           (. as $root | .content | split("\n") | map(trim) |
           map(select((test("^[[:space:]]*#") | not) and (length > 0))) | map(
               (split(" ") | map(select(length > 0))) as $tokens
               | {
                   scope: ($tokens[0]), 
                   # Replacing ** and * characters since the identifier can't contain special characters
                   identifier: ($tokens[0] 
                             | gsub("\\*\\*"; "doublestar")
                             | gsub("\\*"; "star")),
                   # Extracting users and teams to their respective arrays
                   users: (
                       $tokens[1:]
                       | map(select(contains("/") | not)
                               | gsub("@" ; "")
                             )
                     ),
                   teams: (
                       $tokens[1:]
                       | map(select(test("^@[^ ]+/[^ ]+$"))
                             | split("/")
                             | .[-1]
                 ))
               }
               )
             )
         entity:
           mappings:
             identifier: .repository.full_name + "_" +.item.identifier + "_codeowners"
             title: .item.scope + " codeowners"
             blueprint: '"githubCodeowners"'
             properties:
               scope: .item.scope
               location: .path
             relations:
               repository: .repository.full_name
               teams: 
                 combinator: '''and'''
                 rules:
                   - property: '"$title"'
                     value: .item.teams
                     operator: '"in"'
               users: 
                 combinator: '''and'''
                 rules:
                   - property: '"git_hub_username"'
                     value: .item.users
                     operator: '"in"'
   

Ocean differences

GitHub (Ocean) uses .content instead of .file.content for file content, and .path instead of .file.path. The repository relation uses .repository.full_name. Add organization and repos to the file selector to scope which repositories are scanned.

GitHub (Sunset)

1. Go to the data sources page of your portal.

2. Under Exporters, click on your desired GitHub organization.

3. A window will open containing the default YAML configuration of your GitHub integration.

4. In the bottom-left corner you can modify the configuration to suit your needs, by adding/removing entries.

5. Copy the following configuration and paste it in the editor, then click Save & Resync:

   CODEOWNERS mapping configuration (Click to expand)

   resources:
     - kind: file
       selector:
         query: .repo.archived == false
         files:
           - path: '**/.github/CODEOWNERS'
       port:
         itemsToParse: >-
           (. as $root | .file.content | split("\n") | map(trim) |
           map(select((test("^[[:space:]]*#") | not) and (length > 0))) | map(
               (split(" ") | map(select(length > 0))) as $tokens
               | {
                   scope: ($tokens[0]), 
                   # Replacing ** and * characters since the identifier can't contain special characters
                   identifier: ($tokens[0] 
                             | gsub("\\*\\*"; "doublestar")
                             | gsub("\\*"; "star")),
                   # Extracting users and teams to their respective arrays
                   users: (
                       $tokens[1:]
                       | map(select(contains("/") | not)
                               | gsub("@" ; "")
                             )
                     ),
                   teams: (
                       $tokens[1:]
                       | map(select(test("^@[^ ]+/[^ ]+$"))
                             | split("/")
                             | .[-1]
                 ))
               }
               )
             )
         entity:
           mappings:
             identifier: .repo.full_name + "_" +.item.identifier + "_codeowners"
             title: .item.scope + " codeowners"
             blueprint: '"githubCodeowners"'
             properties:
               scope: .item.scope
               location: .file.path
             relations:
               repository: .repo.full_name
               teams: 
                 combinator: '''and'''
                 rules:
                   - property: '"$title"'
                     value: .item.teams
                     operator: '"in"'
               users: 
                 combinator: '''and'''
                 rules:
                   - property: '"git_hub_username"'
                     value: .item.users
                     operator: '"in"'
   

Example

For the following CODEOWNERS file example:

CODEOWNERS file example (Click to expand)

# Default owner for all files in the repo
*                @sivanelk97 @sivan27

# Backend ownership
/backend/         @sivanelk97 @sivan-org/backend-team @sivan-org/docs-team

# Frontend ownership (multiple owners)
/frontend/        @sivanelk97

# Specific file
/README.md        @sivanelk97

# JavaScript files in any folder
**/*.js           @sivanelk97

# Terraform files anywhere
**/*.tf          @sivanelk97

# CI/CD workflows
.github/workflows/  @sivanelk97

# Config files named 'config.yaml' in any folder
**/config.yaml    @sivanelk97

# Markdown documentation files
*.md              @sivanelk97 @sivan27 @sivan-org/docs-team

The software catalog Codeowners page should display the corresponding Codeowners entities: