Skip to main content

Check out Port for yourself ➜ 

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 one or more steps that require integration with GitHub.
Port supports two GitHub integrations:

  • GitHub (Legacy) - uses a GitHub app, which is soon to be deprecated.
  • GitHub (Ocean) - uses the Ocean framework, recommended for new integrations.

Both integration options are present in this guide via tabs, choose the one that fits your needs.

Prerequisites​

  • A Port account.
  • 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​

  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: