> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

Ingest repository files into your context lake

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

Open in ClaudeOpen in CodexOpen in Cursor
Open plan mode. Implement this Port guide in my org via MCP:

https://docs.port.io/guides/all/ingest-repository-files-into-your-context-lake

Goal: get the guide's core flow working end-to-end in my org; adapting it to fit my existing setup takes priority over matching the guide 1:1.

Plan:
1. Confirm MCP is connected, in the right org, with sufficient permissions.
2. Diff the guide's data model (blueprints, properties, relations, actions, agents, automations, integrations, secrets) against mine.
3. Propose adaptations for gaps, reusing existing blueprints/relations over guide-named duplicates.
4. Flag what needs a UI click, credential, or secret from me, testing MCP capability empirically before ruling anything out.
5. Stop on any blocker and give me options. Approving this plan authorizes the writes it lists; pause only for writes beyond what's listed.

Build:
- Extend blueprint schema additively when upserting; don't remove or overwrite existing properties, and treat type conflicts as a blocker, not an auto-fix.
- List any mock data in the plan, minimal and labeled mock; once approved, seed it without re-asking, and tell me what you seeded.
- For anything the guide writes downstream (e.g. a webhook target), use a real entity, not a mock.
- For pages/widgets, use the real page identifier from the app URL, not a guessed slug.
- When you hit a UI step confirmed (not assumed) unsupported via MCP, pause, give exact clicks, then resume via MCP.
- Validate and give links after each meaningful step (only a tool-returned URL, no guessed paths); don't proceed if the last run wasn't a success.

Done:
- Confirm the guide's expected output exists and runs in Port.
- Summarize adaptations, seeded data, what was mocked or skipped, remaining UI steps, and how to verify.

This guide demonstrates how to parse structured files from your repositories and ingest their contents into Port. You can use the same file ingestion pattern for package dependencies, API paths, software bills of materials (SBOMs), SARIF issues, Trivy vulnerabilities, and Checkmarx KICS results.

Each example defines the data model and mapping required for its file format. Choose only the examples that match the files and entities you want to track.

Common use cases​

  • Relate dependencies from package.json files to the services that use them.
  • Catalog API operations from OpenAPI specifications.
  • Track components and vulnerabilities from CycloneDX SBOM files.
  • Relate SARIF security findings to affected services.
  • Ingest Trivy and Checkmarx KICS scan results from repository files.

Prerequisites​

This guide assumes the following:

  • You have a Port account and have completed the onboarding process.
  • You have installed and configured the GitHub integration.
  • Your repositories contain at least one of the supported files described in this guide.
  • The service and repository blueprints exist when an example relates ingested entities to them.

The SARIF pattern can also use the GitLab integration. The mappings in this guide use GitHub's file selector fields, so adjust the selector and repository expressions when you use GitLab.

Understand the file ingestion pattern​

Port's Git integrations use the file kind to locate repository files. The mapping then parses the file's contents and creates one entity for each selected item.

Every file mapping has the same main parts:

  • selector.files finds files by path and scopes the repositories to scan.
  • port.itemsToParse converts the file contents into the items you want to ingest.
  • port.entity.mappings maps each item to an entity identifier, title, blueprint, properties, and relations.
File ingestion pattern (Click to expand)
resources:
  - kind: file
    selector:
      query: 'true'
      files:
        - path: '**/<FILE_NAME>'
          organization: my-org
          repos:
            - name: MyRepo
              branch: main
    port:
      itemsToParse: .content.<ARRAY_TO_PARSE>
      entity:
        mappings:
          identifier: .item.<UNIQUE_FIELD>
          title: .item.<DISPLAY_FIELD>
          blueprint: '"<BLUEPRINT_IDENTIFIER>"'
          properties: {}
          relations: {}

For GitHub Ocean, use .content to read file contents. The integration also exposes repository context through .repository and .__repository, depending on the target relation.

Configure GitHub file ingestion​

Choose whether to manage the shared integration mapping in Port or in a port-app-config.yml file in GitHub.

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

  2. Select your GitHub integration.

  3. Add the mapping from your chosen example to the YAML editor.

  4. Click Save & Resync to apply the mapping.

This method applies the configuration to every repository that the GitHub app can access.

Choose one configuration source

Configuration saved in Port's UI overrides port-app-config.yml files in GitHub.

Apply the pattern to your repository files​

Select a file type to view its complete data model and mapping. The two package.json options represent different models: Dependencies creates shared dependency entities and relates services to them, while Packages creates package entities that point back to services.

Relate package dependencies to services

Use this pattern to parse the dependencies object in each package.json file, create shared dependency entities, and relate each service to the dependencies it uses.

Create the dependency blueprint

  1. Go to the Builder page.

  2. Click + Blueprint.

  3. Click Edit JSON.

  4. Copy and paste the following JSON configuration into the editor:

    Dependency blueprint (Click to expand)
    {
      "identifier": "dependency",
      "title": "Dependency",
      "icon": "Package",
      "schema": {
        "properties": {
          "package_name": {
            "icon": "DefaultProperty",
            "type": "string",
            "title": "Package name"
          },
          "semver_requirement": {
            "type": "string",
            "title": "Semver requirement"
          },
          "type": {
            "type": "string",
            "title": "Type",
            "enum": [
              "Production",
              "Development"
            ]
          },
          "url": {
            "type": "string",
            "title": "URL",
            "format": "url"
          }
        },
        "required": [
          "package_name",
          "semver_requirement"
        ]
      },
      "mirrorProperties": {},
      "calculationProperties": {},
      "aggregationProperties": {},
      "relations": {}
    }

  5. Click Save to create the blueprint.

Ingest dependencies from package.json

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

  2. Select your GitHub integration.

  3. Add the following YAML block to the editor:

    Dependency file mapping (Click to expand)
    - kind: file
      selector:
        query: 'true'
        files:
          - path: '**/package.json'
            organization: my-org
            repos:
              - name: MyRepo
                branch: main
      port:
        itemsToParse: .content.dependencies | to_entries
        entity:
          mappings:
            identifier: >-
              .item.key + "_" +  (.item.value |  gsub("\\^"; "caret_") |
              gsub("~"; "tilde_") |  gsub(">="; "gte_") |  gsub("<="; "lte_") |
              gsub(">"; "gt_") |  gsub("<"; "lt_") |  gsub("@"; "at_") |
              gsub("\\*"; "star") |  gsub(" "; "_"))
            title: .item.key + "@" + .item.value
            blueprint: '"dependency"'
            properties:
              package_name: .item.key
              semver_requirement: .item.value

  4. Click Save & Resync to ingest the dependencies.

The mapping converts each entry in dependencies into an entity. Its identifier replaces characters that Port cannot use in entity identifiers while preserving the package name and semantic version requirement.

Relate dependencies to each service

  1. Go to the Builder page.

  2. Select the Service blueprint.

  3. Click Edit JSON.

  4. Add the following relation to the blueprint's relations object:

    "dependencies": {
      "title": "Dependencies",
      "target": "dependency",
      "required": false,
      "many": true
    }

  5. Click Save.

Choose how the file mapping will populate the new relation:

Use this mapping when the dependency identifiers can be constructed directly from each package.json entry.

Direct dependency relation mapping (Click to expand)
- kind: file
  selector:
    query: 'true'
    files:
      - path: '**/package.json'
        organization: my-org
        repos:
          - name: MyRepo
            branch: main
  port:
    entity:
      mappings:
        identifier: .repository.name
        blueprint: '"service"'
        properties: {}
        relations:
          dependencies: >-
            [.content.dependencies | to_entries | map( .key + "_" +
            (.value |
              gsub("\\^"; "caret_") |
              gsub("~"; "tilde_") |
              gsub(">="; "gte_") |
              gsub("<="; "lte_") |
              gsub(">"; "gt_") |
              gsub("<"; "lt_") |
              gsub("@"; "at_") |
              gsub("\\*"; "star") |
              gsub(" "; "_")
            ) ) | .[]]

After choosing a relation mapping, update your GitHub data source:

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

  2. Select your GitHub integration.

  3. Add the selected relation mapping to the YAML editor.

  4. Click Save & Resync to apply the mapping.

If you manage the integration through GitHub, add the mapping to the configured port-app-config.yml file and commit the change instead. The service entity page will then show its package dependencies.

Service entity page with package dependencies

Let's test it!​

After you save a mapping, verify that Port can find the files and create the expected entities:

  1. Commit a supported file to a repository and branch included by the mapping's files selector.

  2. Go to the Data sources page and select your Git integration.

  3. Click Resync.

  4. Review the integration logs for selector or JQ parsing errors.

  5. Open the relevant blueprint in the software catalog and verify the ingested properties and relations.

If no entities appear, confirm that the file path matches the glob, the integration can access the repository, and itemsToParse returns an array.

More relevant guides​