Capabilities
Ingest Git objects
By using Port's Bitbucket integration, you can automatically ingest Bitbucket resources into Port based on real-time events.
The integration allows you to ingest a variety of objects resources provided by the Bitbucket API, including repositories, pull requests and files. It also allows you to perform "extract, transform, load (ETL)" on data from the Bitbucket API into the desired software catalog data model.
When you install the integration, Port will automatically create a bitbucketProject, bitbucketRepository and bitbucketPullRequest blueprints in your catalog (representing a BitBucket project, repository and pull request respectively).
The YAML configuration mapping will also be added to the data sources page of your portal where you can manage the integration.
Ingest files from your repositories
The file kind requires a user-scoped token for authentication to access Bitbucket's file/code search API. While existing app passwords also work, new app passwords cannot be created as of September 9, 2025. Workspace tokens do not support file ingestion.
Port allows you to fetch JSON and YAML files from your repositories, and create entities from them in your software catalog. This is done using the file kind in your Bitbucket mapping configuration. Changes to the files are tracked through repository push events and periodic resyncs.
For example, say you want to manage your package.json files in Port. One option is to create a manifest blueprint, with each of its entities representing a package.json file.
The following configuration fetches all package.json files from "MyRepo" and "MyOtherRepo", and creates an entity for each of them, based on the manifest blueprint:
resources:
# IMPORTANT: The 'file' kind requires user-scoped token (or existing app password)
# Workspace tokens do not support file ingestion
# New app passwords cannot be created - use user-scoped token instead
- kind: file
selector:
query: 'true'
files:
# Note that glob patterns are not supported, so you can use only '*' wildcard to match multiple directories and subdirectories
path: '/*'
filenames:
- package.json
# The `repos` key can be used to filter the repositories from which the files will be fetched
repos:
- "MyRepo"
- "MyOtherRepo"
skipParsing: false
port:
entity:
mappings:
identifier: .file.path
title: .file.name
blueprint: '"manifest"'
properties:
project_name: .content.name
project_version: .content.version
license: .content.license
After adding the file kind to your mapping configuration, click on the Resync button. When you open the mapping configuration again, you will see real examples of files fetched from your Bitbucket organization.
This will help you see what data is available to use in your jq expressions.
Click on the Test mapping button to test your mapping against the example data.
In any case, the structure of the available data looks like this:Available data example (click to expand)
{
"content":{
"name":"my-awesome-project",
"version":"1.0.0",
"description":"A sample Node.js project",
"main":"index.js",
"scripts":{
"start":"node index.js",
"test":"echo \"Error: no test specified\" && exit 1"
},
"dependencies":{
"express":"^4.17.1"
}
},
"metadata":{
"path":"package.json",
"commit":{
"hash":"fe0dce2d09e1545068b8f5b4b95807c12b49c1f4",
"links":{
"self":{
"href":"https://api.bitbucket.org/2.0/repositories/port-test/port-repo-3/commit/fe0dce2d09e1545068b8f5b4b95807c12b49c1f4"
},
"html":{
"href":"https://bitbucket.org/port-test/port-repo-3/commits/fe0dce2d09e1545068b8f5b4b95807c12b49c1f4"
}
},
"type":"commit",
"repository":{
"type":"repository",
"full_name":"port-test/port-repo-3",
"links":{
"self":{
"href":"https://api.bitbucket.org/2.0/repositories/port-test/port-repo-3"
},
"html":{
"href":"https://bitbucket.org/port-test/port-repo-3"
},
"avatar":{
"href":"https://bytebucket.org/ravatar/%7B14892ea7-2241-4b96-a37a-93ab59b6479b%7D?ts=default"
}
},
"name":"port-repo-3",
"uuid":"{14892ea7-2241-4b96-a37a-93ab59b6479b}",
"mainbranch":{
"name":"new"
}
}
},
"type":"commit_file",
"links":{
"self":{
"href":"https://api.bitbucket.org/2.0/repositories/port-test/port-repo-3/src/fe0dce2d09e1545068b8f5b4b95807c12b49c1f4/package.json"
}
}
},
"repo":{
"type":"repository",
"full_name":"port-test/port-repo-3",
"links":{
"self":{
"href":"https://api.bitbucket.org/2.0/repositories/port-test/port-repo-3"
},
"html":{
"href":"https://bitbucket.org/port-test/port-repo-3"
},
"avatar":{
"href":"https://bytebucket.org/ravatar/%7B14892ea7-2241-4b96-a37a-93ab59b6479b%7D?ts=default"
}
},
"name":"port-repo-3",
"uuid":"{14892ea7-2241-4b96-a37a-93ab59b6479b}",
"mainbranch":{
"name":"main"
}
},
"branch":"main"
}
Create multiple entities from a single file
In some cases, we would like to parse a single JSON/YAML file and create multiple entities from it.
For this purpose, we can use the itemsToParse key in our mapping configuration.
For example, say you want to track/manage a project's dependencies in Port. One option is to create a package blueprint, with each of its entities representing a dependency from a package.json file.
The following configuration fetches a package.json file from a specific repository, and creates an entity for each of the dependencies in the file, based on the package blueprint:
resources:
# IMPORTANT: The 'file' kind requires user-scoped token (or existing app password)
# Workspace tokens do not support file ingestion
# New app passwords cannot be created - use user-scoped token instead
- kind: file
selector:
query: 'true'
files:
path: '/*'
filenames:
- package.json
# Note that in this case we are fetching from a specific repository
repos:
- "MyRepo"
skipParsing: false
port:
itemsToParse: .content.dependencies | to_entries
entity:
mappings:
# Since identifier cannot contain special characters, we are using jq to remove them
identifier: >-
.item.key + "_" + if (.item.value | startswith("^")) then
.item.value[1:] else .item.value end
title: .item.key + "@" + .item.value
blueprint: '"package"'
properties:
package: .item.key
version: .item.value
relations: {}
The itemsToParse key is used to specify the path to the array of items you want to parse from the file. In this case, we are parsing the dependencies array from the package.json file.
Once the array is parsed, we can use the item key to refer to each item in the array.
Multi-document YAML files
For multi-document YAML files (a single file containing multiple YAML documents separated by ---), .content will not resolve to an object, but to an array of objects.
You can use one of these methods to ingest multi-document YAML files:
- Use the
itemsToParsekey to create multiple entities from such a file (see example above). - Map the result to an
arrayproperty.
If you have both single-document and multi-document YAML files in your repositories, you can use the itemsToParse key like this to handle both cases:
itemsToParse: .content | if type== "object" then [.] else . end
Path Structure
Files are referenced using paths relative to the repository root. For example:
✅ Valid paths:
/integrations/*docs/src/config/deployment/k8s/
❌ Invalid paths:
/README.md(leading slash)C:/repo/config.json(absolute path)../other-repo/file.txt(parent directory reference)**/*.yaml(unsupported glob pattern)
Best Practices
For optimal performance and maintainability:
- Limit the number of tracked files per repository
- Use the
reposselector to scope file ingestion to specific repositories - Use
skipParsing: truefor non-JSON/YAML files
Limitations
The following limitations apply to the file mapping feature in the Bitbucket integration:
- File Size: Files must be 320kb or smaller to be ingested
- Path Patterns: Only the
*wildcard is supported in paths. Other glob patterns (e.g.,**/*.json) are not supported - Branch Support: Only files from the default branch can be ingested
- Special Characters: Special characters in filenames are automatically stripped by the API