diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_category_.json b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_category_.json new file mode 100644 index 0000000000..03c598e64f --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "GitHub Self-Hosted (Beta)", + "position": 1 +} diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx new file mode 100644 index 0000000000..56dc95b523 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx @@ -0,0 +1,11 @@ +| Parameter | Description | Example | Required | +| --------- | ----------- | ------- | -------- | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | The Github access token used to authenticate with your Github Organization | | ✅ | +| `OCEAN__INTEGRATION__CONFIG__GTIHUB_HOST` | The URL of your Github organization (will default to https://api.github.com, pass your self-hosted URL) | | ❌ | +| `OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION` | The name of your Github organization | | ✅ | +| `OCEAN__BASE_URL` | The URL of your GitHub integration instance, used for real-time updates | | ❌ | +| `OCEAN__PORT__CLIENT_ID` | Your Port client ([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) id | | ✅ | +| `OCEAN__PORT__CLIENT_SECRET` | Your Port client ([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) secret | | ✅ | +| `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | +| `OCEAN__INITIALIZE_PORT_RESOURCES` | Default true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | | ❌ | +| `OCEAN__INTEGRATION__IDENTIFIER` | The identifier of the integration that will be installed | | ❌ | diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx new file mode 100644 index 0000000000..a88e7eb1ce --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx @@ -0,0 +1,4 @@ +- [`repository`](https://docs.github.com/en/rest/repos/repos#get-a-repository) +- [`pull-request`](https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request) +- [`file`](/build-your-software-catalog/sync-data-to-catalog/git/github/#ingest-files-from-your-repositories) + diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_category_.json b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_category_.json new file mode 100644 index 0000000000..4810441a09 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Examples", + "position": 2 +} diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx new file mode 100644 index 0000000000..1daf460847 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx @@ -0,0 +1,52 @@ +
+ + Port port-app-config.yml + +```yaml showLineNumbers +resources: + - kind: repository + selector: + query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. + port: + entity: + mappings: + identifier: ".name" # The Entity identifier will be the repository name. + title: ".name" + blueprint: '"githubRepository"' + properties: + readme: file://README.md # fetching the README.md file that is within the root folder of the repository and ingesting its contents as a markdown property + url: .html_url + defaultBranch: .default_branch + - kind: pull-request + selector: + query: "true" # JQ boolean query. If evaluated to false - skip syncing the object. + port: + entity: + mappings: + identifier: ".head.repo.name + (.id|tostring)" # The Entity identifier will be the repository name + the pull request ID. + title: ".title" + blueprint: '"githubPullRequest"' + properties: + creator: ".user.login" + assignees: "[.assignees[].login]" + reviewers: "[.requested_reviewers[].login]" + status: ".status" # merged, closed, opened + closedAt: ".closed_at" + updatedAt: ".updated_at" + mergedAt: ".merged_at" + createdAt: ".created_at" + prNumber: ".id" + link: ".html_url" + leadTimeHours: >- + (.created_at as $createdAt | .merged_at as $mergedAt | + ($createdAt | sub("\\..*Z$"; "Z") | strptime("%Y-%m-%dT%H:%M:%SZ") | mktime) as $createdTimestamp | + ($mergedAt | if . == null then null else sub("\\..*Z$"; "Z") | + strptime("%Y-%m-%dT%H:%M:%SZ") | mktime end) as $mergedTimestamp | + if $mergedTimestamp == null then null else + (((($mergedTimestamp - $createdTimestamp) / 3600) * 100 | floor) / 100) end) + + relations: + repository: .__repository +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_pull_request_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_pull_request_blueprint.mdx new file mode 100644 index 0000000000..3fce83007a --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_pull_request_blueprint.mdx @@ -0,0 +1,84 @@ +
+Pull request blueprint + +```json showLineNumbers +{ + "identifier": "githubPullRequest", + "title": "Pull Request", + "icon": "Github", + "schema": { + "properties": { + "creator": { + "title": "Creator", + "type": "string" + }, + "assignees": { + "title": "Assignees", + "type": "array" + }, + "reviewers": { + "title": "Reviewers", + "type": "array" + }, + "status": { + "title": "Status", + "type": "string", + "enum": ["merged", "open", "closed"], + "enumColors": { + "merged": "purple", + "open": "green", + "closed": "red" + } + }, + "closedAt": { + "title": "Closed At", + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "title": "Updated At", + "type": "string", + "format": "date-time" + }, + "mergedAt": { + "title": "Merged At", + "type": "string", + "format": "date-time" + }, + "createdAt": { + "title": "Created At", + "type": "string", + "format": "date-time" + }, + "link": { + "format": "url", + "type": "string" + }, + "leadTimeHours": { + "title": "Lead Time in hours", + "type": "number" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": { + "days_old": { + "title": "Days Old", + "icon": "DefaultProperty", + "calculation": "(now / 86400) - (.properties.createdAt | capture(\"(?\\\\d{4}-\\\\d{2}-\\\\d{2})\") | .date | strptime(\"%Y-%m-%d\") | mktime / 86400) | floor", + "type": "number" + } + }, + "relations": { + "repository": { + "title": "Repository", + "target": "githubRepository", + "required": false, + "many": false + } + } +} +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx new file mode 100644 index 0000000000..f1d8fef28f --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx @@ -0,0 +1,34 @@ +
+Repository blueprint + +```json showLineNumbers +{ + "identifier": "githubRepository", + "title": "Repository", + "icon": "Microservice", + "schema": { + "properties": { + "readme": { + "title": "README", + "type": "string", + "format": "markdown" + }, + "url": { + "title": "Repository URL", + "type": "string", + "format": "url" + }, + "defaultBranch": { + "title": "Default branch", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": {} +} +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_example_package_blueprint.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_example_package_blueprint.mdx new file mode 100644 index 0000000000..ef024ed571 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_example_package_blueprint.mdx @@ -0,0 +1,34 @@ +
+Package blueprint + +```json showLineNumbers +{ + "identifier": "package", + "title": "Package", + "icon": "Package", + "schema": { + "properties": { + "package": { + "icon": "DefaultProperty", + "type": "string", + "title": "Package" + }, + "version": { + "icon": "DefaultProperty", + "type": "string", + "title": "Version" + } + }, + "required": [ + "package", + "version" + ] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} +} +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx new file mode 100644 index 0000000000..0497fc7811 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_package_json_app_config.mdx @@ -0,0 +1,28 @@ +
+ +Port config YAML + +```yaml showLineNumbers + - kind: file + selector: + query: 'true' + files: + - path: package.json + repos: + - name: vscode + branch: main + port: + itemsToParse: .content.dependencies | to_entries + entity: + mappings: + 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 +``` + +
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/resource-mapping-examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/resource-mapping-examples.md new file mode 100644 index 0000000000..03a42c448f --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/resource-mapping-examples.md @@ -0,0 +1,67 @@ +--- +sidebar_position: 1 +--- + +import RepositoryBlueprint from './\_github_exporter_example_repository_blueprint.mdx' +import PRBlueprint from './\_github_exporter_example_pull_request_blueprint.mdx' +import PortAppConfig from './\_github_exporter_example_port_app_config.mdx' +import GitHubResources from '../\_github_exporter_supported_resources.mdx' + +import PackageBlueprint from './example-file-kind/\_example_package_blueprint.mdx' +import PackageAppConfig from './example-file-kind/\_package_json_app_config.mdx' + + +# Resource mapping examples + +:::warning General permissions limitation with gitHub cloud app +When using the GitHub Cloud app with Port, certain fields and data points may not be accessible due to the lack of `write` API permissions. These limitations affect advanced repository settings, security features (such as code scanning and secret scanning status), and other GitHub objects that require elevated permissions to retrieve data. + +If you need to ingest these fields, consider one of the following approaches: +- Use our [self-hosted](/build-your-software-catalog/sync-data-to-catalog/git/github/self-hosted-installation) GitHub app which gives you options to enable appropriate `write` permissions. + +- Implement a GitHub workflow to manually gather and send the required data to Port. + +Refer to specific sections below where these limitations might apply. +::: + +## Map repositories and pull requests + +In the following example you will ingest your GitHub repositories, their README.md file contents and pull requests to Port, you may use the following Port blueprint definitions and `port-app-config.yml`: + + + + + + + +:::tip learn more + +- Refer to the [setup](/build-your-software-catalog/sync-data-to-catalog/git/github/github.md#setup) section to learn more about the `port-app-config.yml` setup process. +- We leverage [JQ JSON processor](https://stedolan.github.io/jq/manual/) to map and transform GitHub objects to Port Entities. +- Click [Here](https://docs.github.com/en/rest/repos/repos#get-a-repository) for the GitHub repository object structure. +- Click [Here](https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request) for the GitHub pull request object structure. + +::: + +After creating the blueprints and committing the `port-app-config.yml` file to your `.github-private` repository (for global configuration), or to any specific repositories (for per-repo configuration), you will see new entities in Port matching your repositories alongside their README.md file contents and pull requests. (Remember that the `port-app-config.yml` file has to be in the **default branch** of the repository to take effect). + +## Map files and file contents + +The following example demonstrates ingestion of dependencies from a `package.json` file in your repository into Port: + + + + +The example will parse the `package.json` file in your repository and extract the dependencies into Port entities. +For more information about ingesting files and file contents, click [here](/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/#ingest-files-from-your-repositories). + + + +## Map supported resources + +The examples above show specific use cases, but Port's GitHub integration supports the ingestion of many other GitHub objects. +To adapt the examples above, use the GitHub API reference to learn about the available fields for the different supported objects: + + + +When adding the ingestion of other resources, remember to add an entry to the `resources` array and change the value provided to the `kind` key accordingly. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md new file mode 100644 index 0000000000..24241cfd24 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/github-ocean.md @@ -0,0 +1,710 @@ +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import GitHubResources from './\_github_exporter_supported_resources.mdx' + +# GitHub Self-Hosted (Beta) + +You can use Port's GitHub integration to ingest and model your GitHub resources in Port's software catalog. 🐙 + + +## Overview + +Here's what you can do with the GitHub integration: + +- Map and organize your desired GitHub resources and their metadata in Port (see supported resources below). +- Watch for GitHub object changes (create/update/delete) in real-time, and automatically apply the changes to your software catalog. +- Manage Port entities using GitOps. +- Trigger GitHub workflows directly from Port. + + +### Supported resources + +The resources that can be ingested from GitHub into Port are listed below. +It is possible to reference any field that appears in the API responses linked below in the mapping configuration. + + + + +## Setup + +To install Port's GitHub integration, see [our dedicated installation guides](./installation). + + +## Configuration + +Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port. + +The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API. + +To ingest GitHub objects, use one of the following methods: + + + + + +To manage your GitHub integration configuration using Port: + +1. Go to the [data sources](https://app.getport.io/settings/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. Here you can modify the configuration to suit your needs, by adding/removing entries. +5. When finished, click `resync` to apply any changes. + +Using this method applies the configuration to all repositories that the GitHub app has permissions to. + +When configuring the integration **using Port**, the YAML configuration is global, allowing you to specify mappings for multiple Port blueprints. + + + + + +## Capabilities + +### Ingesting Git objects + +Using Port's GitHub integration, you can automatically ingest GitHub resources into Port based on real-time events. + +The app allows you to ingest a variety of objects resources provided by the GitHub API, including repositories, pull requests, workflows and more. It also allows you to perform "extract, transform, load (ETL)" on data from the GitHub API into the desired software catalog data model. + +The GitHub integration uses a YAML configuration file to describe the ETL process to load data into the developer portal. This approach provides a flexible and powerful way to model your Git data without being overly opinionated or complex. + +### Ingest files from your repositories + +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 Github mapping configuration. + +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: + +```yaml showLineNumbers +resources: + - kind: file + selector: + query: 'true' + files: + # Note that glob patterns are supported, so you can use wildcards to match multiple files + - path: '**/package.json' + # The `repos` key can be used to filter the repositories and branch where files should be fetched + repos: + - name: MyRepo + branch: main + - name: MyOtherRepo + branch: main + port: + entity: + mappings: + identifier: .path + title: .name + blueprint: '"manifest"' + properties: + project_name: .content.name + project_version: .content.version + license: .content.license +``` + +:::tip Test your mapping +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 GitHub 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) + +```json showLineNumbers +{ + "content": { + "name": "code-oss-dev-build", + "version": "1.0.0", + "license": "MIT", + "devDependencies": { + "@azure/core-auth": "^1.9.0", + "@azure/cosmos": "^3", + "@azure/identity": "^4.2.1", + "@azure/msal-node": "^2.16.1", + "@azure/storage-blob": "^12.25.0", + "@electron/get": "^2.0.0", + "@types/ansi-colors": "^3.2.0", + "@types/byline": "^4.2.32", + "@types/debounce": "^1.0.0", + "@types/debug": "^4.1.5", + "@types/fancy-log": "^1.3.0", + "@types/fs-extra": "^9.0.12", + "@types/glob": "^7.1.1", + "@types/gulp": "^4.0.17", + "@types/gulp-filter": "^3.0.32", + "@types/gulp-gzip": "^0.0.31", + "@types/gulp-json-editor": "^2.2.31", + "@types/gulp-rename": "^0.0.33", + "@types/gulp-sort": "^2.0.4", + "@types/gulp-sourcemaps": "^0.0.32", + "@types/jws": "^3.2.10", + "@types/mime": "0.0.29", + "@types/minimatch": "^3.0.3", + "@types/minimist": "^1.2.1", + "@types/mocha": "^9.1.1", + "@types/node": "22.x", + "@types/pump": "^1.0.1", + "@types/rimraf": "^2.0.4", + "@types/through": "^0.0.29", + "@types/through2": "^2.0.36", + "@types/workerpool": "^6.4.0", + "@types/xml2js": "0.0.33", + "@vscode/iconv-lite-umd": "0.7.0", + "@vscode/ripgrep": "^1.15.13", + "@vscode/vsce": "2.20.1", + "byline": "^5.0.0", + "debug": "^4.3.2", + "electron-osx-sign": "^0.4.16", + "esbuild": "0.25.5", + "extract-zip": "^2.0.1", + "gulp-merge-json": "^2.1.1", + "gulp-sort": "^2.0.0", + "jsonc-parser": "^2.3.0", + "jws": "^4.0.0", + "mime": "^1.4.1", + "source-map": "0.6.1", + "ternary-stream": "^3.0.0", + "through2": "^4.0.2", + "tree-sitter": "^0.22.4", + "vscode-universal-bundler": "^0.1.3", + "workerpool": "^6.4.0", + "yauzl": "^2.10.0", + "zx": "8.5.0" + }, + "type": "commonjs", + "scripts": { + "compile": "../node_modules/.bin/tsc -p tsconfig.build.json", + "watch": "../node_modules/.bin/tsc -p tsconfig.build.json --watch", + "npmCheckJs": "../node_modules/.bin/tsc --noEmit" + }, + "optionalDependencies": { + "tree-sitter-typescript": "^0.23.2", + "vscode-gulp-watch": "^5.0.3" + } + }, + "repository": { + "id": 1006465568, + "node_id": "R_kgDOO_1yIA", + "name": "vscode", + "full_name": "port-gh-app-dev/vscode", + "private": false, + "owner": { + "login": "port-gh-app-dev", + "id": 216844958, + "node_id": "O_kgDODOzKng", + "avatar_url": "https://avatars.githubusercontent.com/u/216844958?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/port-gh-app-dev", + "html_url": "https://github.com/port-gh-app-dev", + "followers_url": "https://api.github.com/users/port-gh-app-dev/followers", + "following_url": "https://api.github.com/users/port-gh-app-dev/following{/other_user}", + "gists_url": "https://api.github.com/users/port-gh-app-dev/gists{/gist_id}", + "starred_url": "https://api.github.com/users/port-gh-app-dev/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/port-gh-app-dev/subscriptions", + "organizations_url": "https://api.github.com/users/port-gh-app-dev/orgs", + "repos_url": "https://api.github.com/users/port-gh-app-dev/repos", + "events_url": "https://api.github.com/users/port-gh-app-dev/events{/privacy}", + "received_events_url": "https://api.github.com/users/port-gh-app-dev/received_events", + "type": "Organization", + "user_view_type": "public", + "site_admin": false + }, + "html_url": "https://github.com/port-gh-app-dev/vscode", + "description": "Visual Studio Code", + "fork": true, + "url": "https://api.github.com/repos/port-gh-app-dev/vscode", + "forks_url": "https://api.github.com/repos/port-gh-app-dev/vscode/forks", + "keys_url": "https://api.github.com/repos/port-gh-app-dev/vscode/keys{/key_id}", + "collaborators_url": "https://api.github.com/repos/port-gh-app-dev/vscode/collaborators{/collaborator}", + "teams_url": "https://api.github.com/repos/port-gh-app-dev/vscode/teams", + "hooks_url": "https://api.github.com/repos/port-gh-app-dev/vscode/hooks", + "issue_events_url": "https://api.github.com/repos/port-gh-app-dev/vscode/issues/events{/number}", + "events_url": "https://api.github.com/repos/port-gh-app-dev/vscode/events", + "assignees_url": "https://api.github.com/repos/port-gh-app-dev/vscode/assignees{/user}", + "branches_url": "https://api.github.com/repos/port-gh-app-dev/vscode/branches{/branch}", + "tags_url": "https://api.github.com/repos/port-gh-app-dev/vscode/tags", + "blobs_url": "https://api.github.com/repos/port-gh-app-dev/vscode/git/blobs{/sha}", + "git_tags_url": "https://api.github.com/repos/port-gh-app-dev/vscode/git/tags{/sha}", + "git_refs_url": "https://api.github.com/repos/port-gh-app-dev/vscode/git/refs{/sha}", + "trees_url": "https://api.github.com/repos/port-gh-app-dev/vscode/git/trees{/sha}", + "statuses_url": "https://api.github.com/repos/port-gh-app-dev/vscode/statuses/{sha}", + "languages_url": "https://api.github.com/repos/port-gh-app-dev/vscode/languages", + "stargazers_url": "https://api.github.com/repos/port-gh-app-dev/vscode/stargazers", + "contributors_url": "https://api.github.com/repos/port-gh-app-dev/vscode/contributors", + "subscribers_url": "https://api.github.com/repos/port-gh-app-dev/vscode/subscribers", + "subscription_url": "https://api.github.com/repos/port-gh-app-dev/vscode/subscription", + "commits_url": "https://api.github.com/repos/port-gh-app-dev/vscode/commits{/sha}", + "git_commits_url": "https://api.github.com/repos/port-gh-app-dev/vscode/git/commits{/sha}", + "comments_url": "https://api.github.com/repos/port-gh-app-dev/vscode/comments{/number}", + "issue_comment_url": "https://api.github.com/repos/port-gh-app-dev/vscode/issues/comments{/number}", + "contents_url": "https://api.github.com/repos/port-gh-app-dev/vscode/contents/{+path}", + "compare_url": "https://api.github.com/repos/port-gh-app-dev/vscode/compare/{base}...{head}", + "merges_url": "https://api.github.com/repos/port-gh-app-dev/vscode/merges", + "archive_url": "https://api.github.com/repos/port-gh-app-dev/vscode/{archive_format}{/ref}", + "downloads_url": "https://api.github.com/repos/port-gh-app-dev/vscode/downloads", + "issues_url": "https://api.github.com/repos/port-gh-app-dev/vscode/issues{/number}", + "pulls_url": "https://api.github.com/repos/port-gh-app-dev/vscode/pulls{/number}", + "milestones_url": "https://api.github.com/repos/port-gh-app-dev/vscode/milestones{/number}", + "notifications_url": "https://api.github.com/repos/port-gh-app-dev/vscode/notifications{?since,all,participating}", + "labels_url": "https://api.github.com/repos/port-gh-app-dev/vscode/labels{/name}", + "releases_url": "https://api.github.com/repos/port-gh-app-dev/vscode/releases{/id}", + "deployments_url": "https://api.github.com/repos/port-gh-app-dev/vscode/deployments", + "created_at": "2025-06-22T10:36:32Z", + "updated_at": "2025-07-01T12:24:24Z", + "pushed_at": "2025-07-01T12:24:14Z", + "git_url": "git://github.com/port-gh-app-dev/vscode.git", + "ssh_url": "git@github.com:port-gh-app-dev/vscode.git", + "clone_url": "https://github.com/port-gh-app-dev/vscode.git", + "svn_url": "https://github.com/port-gh-app-dev/vscode", + "homepage": "https://code.visualstudio.com", + "size": 957812, + "stargazers_count": 0, + "watchers_count": 0, + "language": "TypeScript", + "has_issues": false, + "has_projects": true, + "has_downloads": true, + "has_wiki": true, + "has_pages": false, + "has_discussions": false, + "forks_count": 0, + "mirror_url": null, + "archived": false, + "disabled": false, + "open_issues_count": 0, + "license": { + "key": "mit", + "name": "MIT License", + "spdx_id": "MIT", + "url": "https://api.github.com/licenses/mit", + "node_id": "MDc6TGljZW5zZTEz" + }, + "allow_forking": true, + "is_template": false, + "web_commit_signoff_required": false, + "topics": [], + "visibility": "public", + "forks": 0, + "open_issues": 0, + "watchers": 0, + "default_branch": "main", + "permissions": { + "admin": false, + "maintain": false, + "push": false, + "triage": false, + "pull": false + }, + "temp_clone_token": "", + "allow_squash_merge": true, + "allow_merge_commit": true, + "allow_rebase_merge": true, + "allow_auto_merge": false, + "delete_branch_on_merge": false, + "allow_update_branch": false, + "use_squash_pr_title_as_default": false, + "squash_merge_commit_message": "COMMIT_MESSAGES", + "squash_merge_commit_title": "COMMIT_OR_PR_TITLE", + "merge_commit_message": "PR_TITLE", + "merge_commit_title": "MERGE_MESSAGE", + "custom_properties": {}, + "organization": { + "login": "port-gh-app-dev", + "id": 216844958, + "node_id": "O_kgDODOzKng", + "avatar_url": "https://avatars.githubusercontent.com/u/216844958?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/port-gh-app-dev", + "html_url": "https://github.com/port-gh-app-dev", + "followers_url": "https://api.github.com/users/port-gh-app-dev/followers", + "following_url": "https://api.github.com/users/port-gh-app-dev/following{/other_user}", + "gists_url": "https://api.github.com/users/port-gh-app-dev/gists{/gist_id}", + "starred_url": "https://api.github.com/users/port-gh-app-dev/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/port-gh-app-dev/subscriptions", + "organizations_url": "https://api.github.com/users/port-gh-app-dev/orgs", + "repos_url": "https://api.github.com/users/port-gh-app-dev/repos", + "events_url": "https://api.github.com/users/port-gh-app-dev/events{/privacy}", + "received_events_url": "https://api.github.com/users/port-gh-app-dev/received_events", + "type": "Organization", + "user_view_type": "public", + "site_admin": false + }, + "parent": { + "id": 41881900, + "node_id": "MDEwOlJlcG9zaXRvcnk0MTg4MTkwMA==", + "name": "vscode", + "full_name": "microsoft/vscode", + "private": false, + "owner": { + "login": "microsoft", + "id": 6154722, + "node_id": "MDEyOk9yZ2FuaXphdGlvbjYxNTQ3MjI=", + "avatar_url": "https://avatars.githubusercontent.com/u/6154722?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/microsoft", + "html_url": "https://github.com/microsoft", + "followers_url": "https://api.github.com/users/microsoft/followers", + "following_url": "https://api.github.com/users/microsoft/following{/other_user}", + "gists_url": "https://api.github.com/users/microsoft/gists{/gist_id}", + "starred_url": "https://api.github.com/users/microsoft/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/microsoft/subscriptions", + "organizations_url": "https://api.github.com/users/microsoft/orgs", + "repos_url": "https://api.github.com/users/microsoft/repos", + "events_url": "https://api.github.com/users/microsoft/events{/privacy}", + "received_events_url": "https://api.github.com/users/microsoft/received_events", + "type": "Organization", + "user_view_type": "public", + "site_admin": false + }, + "html_url": "https://github.com/microsoft/vscode", + "description": "Visual Studio Code", + "fork": false, + "url": "https://api.github.com/repos/microsoft/vscode", + "forks_url": "https://api.github.com/repos/microsoft/vscode/forks", + "keys_url": "https://api.github.com/repos/microsoft/vscode/keys{/key_id}", + "collaborators_url": "https://api.github.com/repos/microsoft/vscode/collaborators{/collaborator}", + "teams_url": "https://api.github.com/repos/microsoft/vscode/teams", + "hooks_url": "https://api.github.com/repos/microsoft/vscode/hooks", + "issue_events_url": "https://api.github.com/repos/microsoft/vscode/issues/events{/number}", + "events_url": "https://api.github.com/repos/microsoft/vscode/events", + "assignees_url": "https://api.github.com/repos/microsoft/vscode/assignees{/user}", + "branches_url": "https://api.github.com/repos/microsoft/vscode/branches{/branch}", + "tags_url": "https://api.github.com/repos/microsoft/vscode/tags", + "blobs_url": "https://api.github.com/repos/microsoft/vscode/git/blobs{/sha}", + "git_tags_url": "https://api.github.com/repos/microsoft/vscode/git/tags{/sha}", + "git_refs_url": "https://api.github.com/repos/microsoft/vscode/git/refs{/sha}", + "trees_url": "https://api.github.com/repos/microsoft/vscode/git/trees{/sha}", + "statuses_url": "https://api.github.com/repos/microsoft/vscode/statuses/{sha}", + "languages_url": "https://api.github.com/repos/microsoft/vscode/languages", + "stargazers_url": "https://api.github.com/repos/microsoft/vscode/stargazers", + "contributors_url": "https://api.github.com/repos/microsoft/vscode/contributors", + "subscribers_url": "https://api.github.com/repos/microsoft/vscode/subscribers", + "subscription_url": "https://api.github.com/repos/microsoft/vscode/subscription", + "commits_url": "https://api.github.com/repos/microsoft/vscode/commits{/sha}", + "git_commits_url": "https://api.github.com/repos/microsoft/vscode/git/commits{/sha}", + "comments_url": "https://api.github.com/repos/microsoft/vscode/comments{/number}", + "issue_comment_url": "https://api.github.com/repos/microsoft/vscode/issues/comments{/number}", + "contents_url": "https://api.github.com/repos/microsoft/vscode/contents/{+path}", + "compare_url": "https://api.github.com/repos/microsoft/vscode/compare/{base}...{head}", + "merges_url": "https://api.github.com/repos/microsoft/vscode/merges", + "archive_url": "https://api.github.com/repos/microsoft/vscode/{archive_format}{/ref}", + "downloads_url": "https://api.github.com/repos/microsoft/vscode/downloads", + "issues_url": "https://api.github.com/repos/microsoft/vscode/issues{/number}", + "pulls_url": "https://api.github.com/repos/microsoft/vscode/pulls{/number}", + "milestones_url": "https://api.github.com/repos/microsoft/vscode/milestones{/number}", + "notifications_url": "https://api.github.com/repos/microsoft/vscode/notifications{?since,all,participating}", + "labels_url": "https://api.github.com/repos/microsoft/vscode/labels{/name}", + "releases_url": "https://api.github.com/repos/microsoft/vscode/releases{/id}", + "deployments_url": "https://api.github.com/repos/microsoft/vscode/deployments", + "created_at": "2015-09-03T20:23:38Z", + "updated_at": "2025-07-01T15:41:46Z", + "pushed_at": "2025-07-01T16:26:22Z", + "git_url": "git://github.com/microsoft/vscode.git", + "ssh_url": "git@github.com:microsoft/vscode.git", + "clone_url": "https://github.com/microsoft/vscode.git", + "svn_url": "https://github.com/microsoft/vscode", + "homepage": "https://code.visualstudio.com", + "size": 1030538, + "stargazers_count": 174062, + "watchers_count": 174062, + "language": "TypeScript", + "has_issues": true, + "has_projects": true, + "has_downloads": true, + "has_wiki": true, + "has_pages": false, + "has_discussions": false, + "forks_count": 33404, + "mirror_url": null, + "archived": false, + "disabled": false, + "open_issues_count": 11291, + "license": { + "key": "mit", + "name": "MIT License", + "spdx_id": "MIT", + "url": "https://api.github.com/licenses/mit", + "node_id": "MDc6TGljZW5zZTEz" + }, + "allow_forking": true, + "is_template": false, + "web_commit_signoff_required": false, + "topics": [ + "editor", + "electron", + "microsoft", + "typescript", + "visual-studio-code" + ], + "visibility": "public", + "forks": 33404, + "open_issues": 11291, + "watchers": 174062, + "default_branch": "main" + }, + "source": { + "id": 41881900, + "node_id": "MDEwOlJlcG9zaXRvcnk0MTg4MTkwMA==", + "name": "vscode", + "full_name": "microsoft/vscode", + "private": false, + "owner": { + "login": "microsoft", + "id": 6154722, + "node_id": "MDEyOk9yZ2FuaXphdGlvbjYxNTQ3MjI=", + "avatar_url": "https://avatars.githubusercontent.com/u/6154722?v=4", + "gravatar_id": "", + "url": "https://api.github.com/users/microsoft", + "html_url": "https://github.com/microsoft", + "followers_url": "https://api.github.com/users/microsoft/followers", + "following_url": "https://api.github.com/users/microsoft/following{/other_user}", + "gists_url": "https://api.github.com/users/microsoft/gists{/gist_id}", + "starred_url": "https://api.github.com/users/microsoft/starred{/owner}{/repo}", + "subscriptions_url": "https://api.github.com/users/microsoft/subscriptions", + "organizations_url": "https://api.github.com/users/microsoft/orgs", + "repos_url": "https://api.github.com/users/microsoft/repos", + "events_url": "https://api.github.com/users/microsoft/events{/privacy}", + "received_events_url": "https://api.github.com/users/microsoft/received_events", + "type": "Organization", + "user_view_type": "public", + "site_admin": false + }, + "html_url": "https://github.com/microsoft/vscode", + "description": "Visual Studio Code", + "fork": false, + "url": "https://api.github.com/repos/microsoft/vscode", + "forks_url": "https://api.github.com/repos/microsoft/vscode/forks", + "keys_url": "https://api.github.com/repos/microsoft/vscode/keys{/key_id}", + "collaborators_url": "https://api.github.com/repos/microsoft/vscode/collaborators{/collaborator}", + "teams_url": "https://api.github.com/repos/microsoft/vscode/teams", + "hooks_url": "https://api.github.com/repos/microsoft/vscode/hooks", + "issue_events_url": "https://api.github.com/repos/microsoft/vscode/issues/events{/number}", + "events_url": "https://api.github.com/repos/microsoft/vscode/events", + "assignees_url": "https://api.github.com/repos/microsoft/vscode/assignees{/user}", + "branches_url": "https://api.github.com/repos/microsoft/vscode/branches{/branch}", + "tags_url": "https://api.github.com/repos/microsoft/vscode/tags", + "blobs_url": "https://api.github.com/repos/microsoft/vscode/git/blobs{/sha}", + "git_tags_url": "https://api.github.com/repos/microsoft/vscode/git/tags{/sha}", + "git_refs_url": "https://api.github.com/repos/microsoft/vscode/git/refs{/sha}", + "trees_url": "https://api.github.com/repos/microsoft/vscode/git/trees{/sha}", + "statuses_url": "https://api.github.com/repos/microsoft/vscode/statuses/{sha}", + "languages_url": "https://api.github.com/repos/microsoft/vscode/languages", + "stargazers_url": "https://api.github.com/repos/microsoft/vscode/stargazers", + "contributors_url": "https://api.github.com/repos/microsoft/vscode/contributors", + "subscribers_url": "https://api.github.com/repos/microsoft/vscode/subscribers", + "subscription_url": "https://api.github.com/repos/microsoft/vscode/subscription", + "commits_url": "https://api.github.com/repos/microsoft/vscode/commits{/sha}", + "git_commits_url": "https://api.github.com/repos/microsoft/vscode/git/commits{/sha}", + "comments_url": "https://api.github.com/repos/microsoft/vscode/comments{/number}", + "issue_comment_url": "https://api.github.com/repos/microsoft/vscode/issues/comments{/number}", + "contents_url": "https://api.github.com/repos/microsoft/vscode/contents/{+path}", + "compare_url": "https://api.github.com/repos/microsoft/vscode/compare/{base}...{head}", + "merges_url": "https://api.github.com/repos/microsoft/vscode/merges", + "archive_url": "https://api.github.com/repos/microsoft/vscode/{archive_format}{/ref}", + "downloads_url": "https://api.github.com/repos/microsoft/vscode/downloads", + "issues_url": "https://api.github.com/repos/microsoft/vscode/issues{/number}", + "pulls_url": "https://api.github.com/repos/microsoft/vscode/pulls{/number}", + "milestones_url": "https://api.github.com/repos/microsoft/vscode/milestones{/number}", + "notifications_url": "https://api.github.com/repos/microsoft/vscode/notifications{?since,all,participating}", + "labels_url": "https://api.github.com/repos/microsoft/vscode/labels{/name}", + "releases_url": "https://api.github.com/repos/microsoft/vscode/releases{/id}", + "deployments_url": "https://api.github.com/repos/microsoft/vscode/deployments", + "created_at": "2015-09-03T20:23:38Z", + "updated_at": "2025-07-01T15:41:46Z", + "pushed_at": "2025-07-01T16:26:22Z", + "git_url": "git://github.com/microsoft/vscode.git", + "ssh_url": "git@github.com:microsoft/vscode.git", + "clone_url": "https://github.com/microsoft/vscode.git", + "svn_url": "https://github.com/microsoft/vscode", + "homepage": "https://code.visualstudio.com", + "size": 1030538, + "stargazers_count": 174062, + "watchers_count": 174062, + "language": "TypeScript", + "has_issues": true, + "has_projects": true, + "has_downloads": true, + "has_wiki": true, + "has_pages": false, + "has_discussions": false, + "forks_count": 33404, + "mirror_url": null, + "archived": false, + "disabled": false, + "open_issues_count": 11291, + "license": { + "key": "mit", + "name": "MIT License", + "spdx_id": "MIT", + "url": "https://api.github.com/licenses/mit", + "node_id": "MDc6TGljZW5zZTEz" + }, + "allow_forking": true, + "is_template": false, + "web_commit_signoff_required": false, + "topics": [ + "editor", + "electron", + "microsoft", + "typescript", + "visual-studio-code" + ], + "visibility": "public", + "forks": 33404, + "open_issues": 11291, + "watchers": 174062, + "default_branch": "main" + }, + "security_and_analysis": { + "secret_scanning": { + "status": "disabled" + }, + "secret_scanning_push_protection": { + "status": "disabled" + }, + "dependabot_security_updates": { + "status": "disabled" + }, + "secret_scanning_non_provider_patterns": { + "status": "disabled" + }, + "secret_scanning_validity_checks": { + "status": "disabled" + } + }, + "network_count": 33404, + "subscribers_count": 1 + }, + "branch": "main", + "path": "build/package.json", + "name": "package.json", + "metadata": { + "url": "https://api.github.com/repos/port-gh-app-dev/vscode/contents/build/package.json?ref=main", + "path": "build/package.json", + "size": 2106 + } +} +``` +
+::: + +#### 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: + +```yaml showLineNumbers +resources: + - kind: file + selector: + query: 'true' + files: + - path: '**/package.json' + # Note that in this case we are fetching from a specific repository + repos: + - name: MyRepo + branch: main + 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: + +1. Use the `itemsToParse` key to create multiple entities from such a file (see example above). +2. Map the result to an `array` property. + +:::tip Mixed YAML types +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: + +```yaml +itemsToParse: .content | if type== "object" then [.] else . end +``` +::: + + +#### Ingest raw file content + +If you need to ingest the raw content of a file without parsing it, you can use the `skipParsing` key in your file selector. +This is useful when you want to store the file content as a string or YAML property. + +When `skipParsing` is set to `true`, the file content will be kept in its original string format instead of being parsed into a JSON/YAML object. + +Here's an example that ingests the raw content of a `values.yaml` file into the `content` property of a `file` entity: + +```yaml +resources: + - kind: file + selector: + query: 'true' + files: + - path: values.yaml + skipParsing: true + port: + entity: + mappings: + identifier: >- + .repository.name + "-values" + blueprint: '"file"' + properties: + content: .content +``` + +#### Limitations + +- Currently only files up to 1MB in size are supported. +- Only JSON and YAML formats are automatically parsed. + Other file formats can be ingested as raw files, however, some special characters in the file (such as `\n`) may be processed and not preserved. + +## Permissions + +Port's GitHub integration requires the following permissions: + +- Repository permissions: + + - **Actions:** Read and Write (for executing self-service action using GitHub workflow). + - **Checks:** Read and Write (for validating `port.yml`). + - **Contents:** Readonly. + - **Metadata:** Readonly. + - **Pull requests:** Read and write. + +- Repository events (required to receive changes via webhook from GitHub and apply the `port-app-config.yml` configuration on them): + - Pull requests + - Push + +:::info Default permissions +You will be prompted to confirm the above listed permissions when creating a personal access token. + +Permissions can be given to selected repositories in your organization, or to all repositories. +You can reconfigure the permission at any time, giving it access to new repositories, or removing access. + +::: + +## Examples + +Refer to the [examples](./examples/resource-mapping-examples.md) page for practical configurations and their corresponding blueprint definitions. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/_category_.json b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/_category_.json new file mode 100644 index 0000000000..35f80e71b7 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "GitOps", + "position": 3 +} diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md new file mode 100644 index 0000000000..a361050571 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/gitops/gitops.md @@ -0,0 +1,169 @@ +--- +sidebar_position: 3 +--- + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import PortYmlStructure from '../../\_port_yml_gitops_structure_template.md' +import BasicFileProperties from '../../\_basic_file_properties_template.md' +import RelativeFileProperties from '../../\_relative_file_properties_template.md' +import GitOpsPushEvent from '../../\_git_gitops_push_events_explanation.mdx' +import PortYmlNullProperties from '../../\_port_yml_null_properties.md' +import PortYmlIngestionPattern from '../../\_port_yml_ingestion_pattern_template.md' + + +# GitOps + +Port's GitHub integration allows you to manage Port entities with a GitOps approach, making your code repositories the source of truth for your infrastructure assets. + +Some common use cases include: + +- Use GitHub as the source-of-truth for your **microservices**, **packages**, **libraries** and other software catalog assets. +- Allow developers to keep the catalog up-to-date, by making updates to files in their Git repositories. +- Create a standardized way to document software catalog assets in your organization. + +Port offers two ways to manage entities using GitOps: + +1. Using a dedicated `port.yml` file in your repository. +2. Using the GitHub integration mapping in your portal. + +## Option 1: Use a `port.yml` file + +This approach requires adding a `port.yml` file to the **default branch** (usually `main`) of your repository. + +Note that the `port.yml` file is not the same as the [`port-app-config.yml` file](/build-your-software-catalog/sync-data-to-catalog/git/github/#port-app-configyml-file) used to configure the GitHub integration, and does not replace it. + +The `port.yml` file can specify one or more Port entities that will be ingested to Port. Any change made to the `port.yml` file will also be reflected inside Port. + +:::tip GitHub integration +To manage entities using GitOps and the `port.yml` file, Port's [GitHub integration](/build-your-software-catalog/sync-data-to-catalog/git/github/#setup) must be installed, as it listens to `push` events sent from Github. + +This means that if the `port.yml` file exists in the repository before installing the integration, it will not be picked up automatically. You will need to make some update to the `port.yml` file and push it to the repository in order for the Git integration to properly track and ingest the entity information. +::: + +The `port.yml` file is how you specify your Port entities that are managed using GitOps and whose data is ingested from your Git repositories. + +Here are examples for valid `port.yml` files: + + + + + +```yaml showLineNumbers +identifier: myEntity +title: My Entity +blueprint: myBlueprint +properties: + myStringProp: myValue + myNumberProp: 5 + myUrlProp: https://example.com +relations: + mySingleRelation: myTargetEntity + myManyRelation: + - myTargetEntity1 + - myTargetEntity2 +``` + + + + + +```yaml showLineNumbers +- identifier: myEntity1 + title: My Entity1 + blueprint: myFirstBlueprint + properties: + myStringProp: myValue + myNumberProp: 5 + myUrlProp: https://example.com + relations: + mySingleRelation: myTargetEntity + myManyRelation: + - myTargetEntity1 + - myTargetEntity2 +- identifier: myEntity + title: My Entity2 + blueprint: mySecondBlueprint + properties: + myStringProp: myValue + myNumberProp: 5 + myUrlProp: https://example.com +``` + + + + + +Since both of the valid `port.yml` formats follow the same structure, the following section will explain the format based on the single entity example. + +### `port.yml` structure + + + + + +### Ingesting repository file contents + + + +#### Using relative paths + + + +## Option 2: Use the integration mapping + +Every integration in Port has a dedicated [mapping configuration](/build-your-software-catalog/customize-integrations/configure-mapping) that allows you to specify which resources to ingest from the integration into Port. + +In the case of the GitHub integration, one of the supported resources is the `file` resource, which allows you to ingest file contents from a repository into your portal. + +To use this approach, you will need to edit your GitHub integration mapping and add a `file` block that specifies which files to ingest. +To edit a mapping configuration: + +1. Go to the [data sources page](https://app.getport.io/settings/data-sources) of your portal. +2. Under `Exporters`, find the GitHub data source and click on it. +3. Scroll down to the `Mapping` section and add a `file` block to the `resources` array. + +For example, say you want to ingest a `package.json` file form your repository. You can add the following to your GitHub integration mapping: + +```yaml +resources: + ... + - kind: file + selector: + query: 'true' + files: + - path: package.json + port: + entity: + mappings: + identifier: .file.name + blueprint: '"file"' + properties: + content: .file.content +``` + +The `selector.files.path` key also supports glob patterns, so you can ingest multiple files by matching against a pattern and create an entity in Port for each one, for example: + +```yaml +- kind: file + selector: + query: 'true' + files: + - path: 'resources/*.yml' +``` + +### Advantages + +- **Resync support**: Since this approach uses the integration mapping, a resync of the integration will update the entities in Port with the latest file contents. + +- **Data manipulation**: Since this approach uses the integration mapping, `jq` is supported and can be used to transform the file contents before ingestion. + +## Examples + +Check out the [example repository](https://github.com/port-labs/github-app-setup-example) for a microservice blueprint and a matching `port.yml` file which specifies a microservice entity. + +## Capabilities + +### Port.yml ingestion pattern + + diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/github-app.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/github-app.md new file mode 100644 index 0000000000..f1aa21dc5b --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/github-app.md @@ -0,0 +1,137 @@ +--- +sidebar_position: 2 +--- + +import FindCredentials from "/docs/build-your-software-catalog/custom-integration/api/\_template_docs/\_find_credentials.mdx" + +# Github App + +:::note Prerequisites + +- A registered organization in Port; +- Your Port user role is set to `Admin`. + +::: + +In organizations that have a self-hosted GitHub installation there is no access to our official public app, therefore there are some extra steps you need to take to install the GitHub integration: + +1. [Register](#register-ports-github-integration) Port's GitHub integration in your GitHub organization; +2. [Deploy](#deployment) Port's GitHub integration Docker image inside your VPC; +3. [Install](#installing-ports-github-integration) Port's GitHub integration in your GitHub organization and on select repositories. + +## Register Port's GitHub integration + +1. Navigate to your Github organization and click on Settings: + +![Org view](../../../../../../static/img/integrations/github-ocean/SelfHostedOrganizaionView.png) + +2. Inside the settings view, click on **Developer Settings** -> and then select **GitHub Apps**: + +![Settings view](../../../../../../static/img/integrations/github-ocean/SelfHostedOrganizationSettings.png) + +3. Click on "New GitHub App": + +![New GitHub App](../../../../../../static/img/integrations/github-ocean/SelfHostedNewGitHubApp.png) + +4. Insert the following properties: + +- **GitHub App name:** port.io +- **Homepage URL:** https://getport.io +- **Repository Permissions:** + - Actions: Read and Write (for executing self-service action using GitHub workflow) + - Checks: Read and Write (for validating `Port.yml`) + - Contents: Readonly (for reading port configuration files and repository files) + - Metadata: Readonly + - Pull Request: Read and Write +- **Organization Permissions:** + - Webhooks: Read and Write (to allow the integration create webhooks) +- **Repository Events** (required to receive webhook changes from GitHub): + - Pull Request + - Push + +Then select "Create GitHub App" + +5. Go to the settings of the created GitHub app and generate a private key. Save the downloaded file: + +![Generate Private key](../../../../../../static/img/integrations/github-app/SelfHosetdGeneratePrivayKey.png) + +Keep the file, you will need it for the deployment step. + +## Deployment + +:::note Prerequisites + +You will need your Port `CLIENT_ID` and `CLIENT_SECRET`. + + + +::: + +In order to make use of [Self-Service Actions using GitHub Workflow](../../../../../actions-and-automations/setup-backend/github-workflow/github-workflow.md), please contact us at support@getport.io. + +## Installing Port's GitHub integration + +After you have the app registered in your organization, you can install it and select the repositories to integrate it with: + +1. First, navigate to your organization and click on Settings: + +![Org view](../../../../../../static/img/integrations/github-ocean/SelfHostedOrganizaionView.png) + +2. Inside the settings view, click on Developer Settings -> and then select GitHub Integrations: + +![Settings view](../../../../../../static/img/integrations/github-ocean/SelfHostedOrganizationSettings.png) + +3. Click `edit` on the GitHub integration created at the step before: + +![GitHub integration installation page](../../../../../../static/img/integrations/github-ocean/SelfHostedEditGitHubApp.png) + +4. Go to Install App -> and select the installation button on your wanted organization; + +5. Choose the repositories you want the integration to be installed for: + +![GitHub integration installation chooses repositories](../../../../../../static/img/integrations/github-ocean/SelfHostedInstallationRepoSelection.png) + +## Docker + +To use our GitHub integration as an app, you will need to deploy our official integration Docker image - providing an app id and an app private key. + +It can be deployed on any platform that allows deploying images as containers such as: K8S, ECS, AWS App Runner, etc. + +You can pull the Docker image by running: + +```bash showLineNumbers +docker pull ghcr.io/port-labs/port-ocean-github-ocean:latest +``` + +Run the following command to start the app: + +```bash showLineNumbers +docker run \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_ID= \ + -e OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRET="test" \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST= \ + -e OCEAN__BASE_URL=https://test.com \ + -e OCEAN__PORT__BASE_URL=https://api.getport.io \ + -e OCEAN__PORT__CLIENT_ID= \ + -e OCEAN__PORT__CLIENT_SECRET= \ + -e OCEAN__INTEGRATION__IDENTIFIER=github-ocean \ + -e OCEAN__EVENT_LISTENER__TYPE=POLLING \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION= \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY= \ + -p 8000:8000 \ + ghcr.io/port-labs/port-ocean-github-ocean:latest +``` + +| Env variable | Description | +| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_APP_ID` | Application ID. You can find it in the edit GitHub app page. | +| `OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRET` | Will be used to create webhook | +| `OCEAN__INTEGRATION__IDENTIFIER` | Your organization's self-hosted GitHub hostname | +| `OCEAN__BASE_URL` | Integration base url, will be used to register webhook. | +| `OCEAN__PORT__BASE_URL` | Port's API Base URL | +| `OCEAN__PORT__CLIENT_ID` | Port client id for interacting with the API | +| `OCEAN__PORT__CLIENT_SECRET` | Port client secret for interacting with the API | +| `OCEAN__INTEGRATION__IDENTIFIER` | Identifier for the integration | +| `OCEAN__EVENT_LISTENER__TYPE` | How Ocean will retrieve config changes from Port. | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION` | The GitHub organization the integration was installed in. | +| `OCEAN__INTEGRATION__CONFIG__GITHUB_APP_PRIVATE_KEY` | A base64 encoded Github app private key. You can use a tool like https://www.base64encode.org/ | diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.md new file mode 100644 index 0000000000..a50281121e --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/installation.md @@ -0,0 +1,388 @@ +--- +sidebar_position: 5 +--- + +import Tabs from "@theme/Tabs" +import TabItem from "@theme/TabItem" +import Prerequisites from "../../../templates/\_ocean_helm_prerequisites_block.mdx" +import HelmParameters from "../../../templates/\_ocean-advanced-parameters-helm.mdx" +import DockerParameters from "../\_github_docker_parameters.mdx" +import AdvancedConfig from '../../../../../generalTemplates/\_ocean_advanced_configuration_note.md' +import PortApiRegionTip from "/docs/generalTemplates/\_port_region_parameter_explanation_template.md" +import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/\_ocean_saas_installation.mdx" +import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/\_ocean_realtime_installation.mdx" +import { OceanSaasLiveEventsDescription, OceanSaasLiveEventsTriggersManual, liveEvents } from "/src/components/ocean-saas-specifics/live-events.jsx"; + +# Installation + +This page details how to install Port's GitHub integration (powered by the Ocean framework). + +This page outlines the following steps: + +- How to [create](#create-an-access-token) an access token to give the integration permissions to query your Github organization. +- How to [configure](#configure-the-integration) and customize the integration before deploying it. +- How to [deploy](#deploy-the-integration) the integration in the configuration that fits your use case. + +## Prerequisites + +- A GitHub account with permissions to create access tokens. +- Your Port user role is set to `Admin`. + +## Setup + +### Configure access token + +To allow Port to fetch data from your GitHub Organization, you need to create an access token. Port supports two types of tokens for authentication: personal access tokens and GitHub app installation tokens. + +#### Personal access token (PAT) + +A Personal Access Token (PAT) is suitable if you're the only one managing the integration and don't need frequent credential rotation. +To create a personal access token see Github's [managing your personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens). + +- The token must belong to a user with access to the relevant Github resources (e.g., repositories, teams). + +#### Github app installation + +Refer to our [Github app installation guide](./github-app.md) + +### Configure Realtime webhook events + +:::tip +The `baseUrl` parameter is used specifically to enable the real-time functionality of the integration. + +If it is not provided, the integration will continue to function correctly. In such a configuration, to retrieve the latest information from the target system, the [`scheduledResyncInterval`](https://ocean.getport.io/develop-an-integration/integration-configuration/#scheduledresyncinterval---run-scheduled-resync) parameter has to be set, or a manual resync will need to be triggered through Port's UI. +::: + +## Deploy the integration + +Choose the installation method that best suits your needs: + + + + + +Using this installation option means that the integration will be able to update Port in real time using webhooks. + +

Prerequisites

+ + + +For details about the available parameters for the installation, see the table below. + + + + + + + + + + + +To install the integration using ArgoCD: + +1. Create a `values.yaml` file in `argocd/my-ocean-github-integration` in your git repository with the content: + +:::note +Remember to replace the placeholders for `GITHUB_TOKEN` and your GitHub URL. +::: + +```yaml showLineNumbers +initializePortResources: true +scheduledResyncInterval: 120 +integration: + identifier: my-ocean-github-integration + type: github-ocean + eventListener: + type: POLLING + config: + // highlight-next-line + githubHost: https://api.github.com # Or your self-hosted GitHub URL + githubOrganization: + secrets: + // highlight-next-line + githubToken: GITHUB_TOKEN +``` + +
+2. Install the `my-ocean-github-integration` ArgoCD Application by creating the following `my-ocean-github-integration.yaml` manifest: +:::note +Remember to replace the placeholders for `YOUR_PORT_CLIENT_ID` `YOUR_PORT_CLIENT_SECRET` and `YOUR_GIT_REPO_URL`. + +Multiple sources ArgoCD documentation can be found [here](https://argo-cd.readthedocs.io/en/stable/user-guide/multiple_sources/#helm-value-files-from-external-git-repository). +::: + +
+ ArgoCD Application + +```yaml showLineNumbers +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: my-ocean-github-integration + namespace: argocd +spec: + destination: + namespace: my-ocean-github-integration + server: https://kubernetes.default.svc + project: default + sources: + - repoURL: 'https://port-labs.github.io/helm-charts/' + chart: port-ocean + targetRevision: 0.8.5 + helm: + valueFiles: + - $values/argocd/my-ocean-github-integration/values.yaml + // highlight-start + parameters: + - name: port.clientId + value: YOUR_PORT_CLIENT_ID + - name: port.clientSecret + value: YOUR_PORT_CLIENT_SECRET + - name: port.baseUrl + value: https://api.getport.io + - repoURL: YOUR_GIT_REPO_URL + // highlight-end + targetRevision: main + ref: values + syncPolicy: + automated: + prune: true + selfHeal: true + syncOptions: + - CreateNamespace=true +``` + + +
+
+ +1. Apply your application manifest with `kubectl`: + +```bash +kubectl apply -f my-ocean-github-integration.yaml +``` + + + + + +This table summarizes the available parameters for the installation. + +| Parameter | Description | Required | +| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -------- | +| `port.clientId` | Your Port client ID. | ✅ | +| `port.clientSecret` | Your Port client secret. | ✅ | +| `port.baseUrl` | Your Port API URL (`https://api.getport.io` for EU, `https://api.us.getport.io` for US). | ✅ | +| `integration.identifier` | A unique identifier for your integration. | ✅ | +| `integration.type` | The integration type. | ✅ | +| `integration.eventListener.type` | The event listener type. | ✅ | +| `integration.config.githubOrganization` | The GitHub organization to sync data from. | ✅ | +| `integration.config.githubHost` | The GitHub instance URL. | ✅ | +| `integration.secrets.githubToken` | The GitHub access token. | ✅ | +| `scheduledResyncInterval` | The number of minutes between each resync. | ❌ | +| `initializePortResources` | When `true`, the integration will create default blueprints and port-app-config.yml mapping. | ❌ | +| `sendRawDataExamples` | When `true`, sends raw data examples from the third-party API to Port for testing and managing the integration mapping. | ❌ | +| `baseUrl` | The base URL of the GitHub integration instance, used for real-time updates. | ❌ | + +
+ + + + + + + +This workflow/pipeline will run the GitHub integration once and then exit. This is useful for **scheduled** ingestion of data. + +:::warning Real-time updates +If you want the integration to update Port in real time using webhooks you should use the [Real-time (self-hosted)](?installation-methods=real-time-self-hosted#setup) installation option. +::: + + + +Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions): + + + +
+ +Here is an example for a `github-integration.yml` workflow file: + +```yaml showLineNumbers +name: Github Exporter Workflow +on: + workflow_dispatch: + schedule: + - cron: "0 */1 * * *" # Determines the scheduled interval for this workflow. This example runs every hour. +jobs: + run-integration: + runs-on: ubuntu-latest + timeout-minutes: 30 # Set a time limit for the job + steps: + - uses: port-labs/ocean-sail@v1 + with: + type: "github-ocean" + port_client_id: ${{ secrets.OCEAN__PORT__CLIENT_ID }} + port_client_secret: ${{ secrets.OCEAN__PORT__CLIENT_SECRET }} + port_base_url: https://api.getport.io + config: | + githubHost: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_HOST }} + githubToken: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN }} + githubOrganization: ${{ secrets.OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION }} +``` + + + + +:::tip +Your Jenkins agent should be able to run docker commands. +::: + +Make sure to configure the following [Jenkins Credentials](https://www.jenkins.io/doc/book/using/using-credentials/) +of `Secret Text` type: + + + +
+ +Here is an example for a `Jenkinsfile` groovy pipeline file: + +```text showLineNumbers +pipeline { + agent any + stages { + stage('Run Github Integration') { + steps { + script { + withCredentials([ + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_URL'), + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION'), + string(credentialsId: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN', variable: 'OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN'), + string(credentialsId: 'OCEAN__PORT__CLIENT_ID', variable: 'OCEAN__PORT__CLIENT_ID'), + string(credentialsId: 'OCEAN__PORT__CLIENT_SECRET', variable: 'OCEAN__PORT__CLIENT_SECRET'), + ]) { + sh(''' + #Set Docker image and run the container + integration_type="github-ocean" + version="latest" + image_name="ghcr.io/port-labs/port-ocean-${integration_type}:${version}" + docker run -i --rm --platform=linux/amd64 \ + -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \ + -e OCEAN__INITIALIZE_PORT_RESOURCES=true \ + -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_URL=$OCEAN__INTEGRATION__CONFIG__GITHUB_URL \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION \ + -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \ + -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \ + -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ + $image_name + exit $? + ''') + } + } + } + } + } +} +``` + + + + + +Make sure to configure the following [Azure DevOps pipeline variables](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/variables): + + + +
+ +Here is an example for a `github-integration.yml` pipeline file: + +```yaml showLineNumbers +trigger: + - main +pool: + vmImage: "ubuntu-latest" +variables: + - group: port-ocean-credentials +steps: + - script: | + # Set Docker image and run the container + integration_type="github-ocean" + version="latest" + image_name="ghcr.io/port-labs/port-ocean-$integration_type:$version" + + docker run -i --rm --platform=linux/amd64 \ + -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \ + -e OCEAN__INITIALIZE_PORT_RESOURCES=true \ + -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST=$(OCEAN__INTEGRATION__CONFIG__GITHUB_HOST) \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$(OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN) \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$(OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION) \ + -e OCEAN__PORT__CLIENT_ID=$(OCEAN__PORT__CLIENT_ID) \ + -e OCEAN__PORT__CLIENT_SECRET=$(OCEAN__PORT__CLIENT_SECRET) \ + -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ + $image_name + exit $? + displayName: "Ingest Data into Port" +``` + + + + +Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project): + + + +
+ +Here is an example for a `.gitlab-ci.yml` pipeline file: + +```yaml showLineNumbers +default: + image: docker:24.0.5 + services: + - docker:24.0.5-dind + before_script: + - docker info + +variables: + INTEGRATION_TYPE: github-ocean + VERSION: latest +stages: + - ingest +ingest_data: + stage: ingest + variables: + IMAGE_NAME: ghcr.io/port-labs/port-ocean-$INTEGRATION_TYPE:$VERSION + script: + - | + docker run -i --rm --platform=linux/amd64 \ + -e OCEAN__EVENT_LISTENER='{"type":"ONCE"}' \ + -e OCEAN__INITIALIZE_PORT_RESOURCES=true \ + -e OCEAN__SEND_RAW_DATA_EXAMPLES=true \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_URL=$OCEAN__INTEGRATION__CONFIG__GITHUB_URL \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN=$OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN \ + -e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION=$OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION \ + -e OCEAN__PORT__CLIENT_ID=$OCEAN__PORT__CLIENT_ID \ + -e OCEAN__PORT__CLIENT_SECRET=$OCEAN__PORT__CLIENT_SECRET \ + -e OCEAN__PORT__BASE_URL='https://api.getport.io' \ + $IMAGE_NAME + rules: # Run only when changes are made to the main branch + - if: '$CI_COMMIT_BRANCH == "main"' + schedule: # Run according to a schedule + - cron: "0 */3 * * *" # Run every 3 hours +``` + + + + + + + + + + + diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx index d682c90fe5..23de0403f3 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab-v2/example-files/_gitlab_integration_example_package_config.mdx @@ -20,4 +20,4 @@ resources: properties: package: .item.key version: .item.value -``` \ No newline at end of file +``` diff --git a/src/components/ocean-saas-specifics/live-events.jsx b/src/components/ocean-saas-specifics/live-events.jsx index a5ee9018e1..ab549fae74 100644 --- a/src/components/ocean-saas-specifics/live-events.jsx +++ b/src/components/ocean-saas-specifics/live-events.jsx @@ -1,18 +1,16 @@ import Markdown from "@theme/Markdown"; const defaultLiveEvents = { - unsupported: - `Currently, live events are not supported for this integration. \ + unsupported: `Currently, live events are not supported for this integration. \ \nResyncs will be performed **periodically** (with a configurable interval), or **manually** triggered by you via Port's UI. \ \n\nTherefore, real-time events (including GitOps) will not be ingested into Port immediately. \ \nLive events support for this integration is WIP and will be supported in the near future.`, supported: - 'This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.', + "This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.", }; export const liveEvents = { - Jira: - '**Issue:** \ + Jira: "**Issue:** \ \n- jira:issue_created \ \n- jira:issue_updated \ \n- jira:issue_deleted \ @@ -23,17 +21,16 @@ export const liveEvents = { \n\n**User:** \ \n- user_created \ \n- user_updated \ - \n- user_deleted', + \n- user_deleted", Jira_OAuth: - '**Issue:** \ + "**Issue:** \ \n- jira:issue_created \ \n- jira:issue_updated \ - \n- jira:issue_deleted', - Snyk: - '\n- Project related events \ - \n- Target related events', + \n- jira:issue_deleted", + Snyk: "\n- Project related events \ + \n- Target related events", BitbucketCloud: - '**Repository:** \ + "**Repository:** \ \n- repository:created \ \n- repository:updated \ \n- repository:push \ @@ -43,9 +40,9 @@ export const liveEvents = { \n- pullrequest:approved \ \n- pullrequest:unapproved \ \n- pullrequest:fulfilled \ - \n- pullrequest:rejected', + \n- pullrequest:rejected", PagerDuty: - '**Service:** \ + "**Service:** \ \n- service.created \ \n- service.deleted \ \n- service.updated \ @@ -62,9 +59,9 @@ export const liveEvents = { \n- incident.responder.added \ \n- incident.responder.replied \ \n- incident.triggered \ - \n- incident.unacknowledged', + \n- incident.unacknowledged", PagerDuty_OAuth: - '**Service:** \ + "**Service:** \ \n- service.created \ \n- service.deleted \ \n- service.updated \ @@ -81,12 +78,12 @@ export const liveEvents = { \n- incident.responder.added \ \n- incident.responder.replied \ \n- incident.triggered \ - \n- incident.unacknowledged', + \n- incident.unacknowledged", SonarQube: - '\n- Analysis completion events \ - \n- Quality gate status change events', - Datadog: - '**Monitoring Alerts:** \ + "\n- Analysis completion events \ + \n- Quality gate status change events", + Datadog: + "**Monitoring Alerts:** \ \n- ci_pipelines_alert \ \n- ci_tests_alert \ \n- composite_monitor \ @@ -102,9 +99,9 @@ export const liveEvents = { \n- rum_alert \ \n- service_check \ \n- synthetics_alert \ - \n- trace_analytics_alert', - Datadog_OAuth: - '**Monitoring Alerts:** \ + \n- trace_analytics_alert", + Datadog_OAuth: + "**Monitoring Alerts:** \ \n- ci_pipelines_alert \ \n- ci_tests_alert \ \n- composite_monitor \ @@ -120,9 +117,9 @@ export const liveEvents = { \n- rum_alert \ \n- service_check \ \n- synthetics_alert \ - \n- trace_analytics_alert', + \n- trace_analytics_alert", GitLab_v2: - '**Groups:** \ + "**Groups:** \ \n- group_create \ \n- group_destroy \ \n- subgroup_create \ @@ -142,33 +139,33 @@ export const liveEvents = { \n\n**Jobs:** \ \n- build \ \n\n**Pipelines:** \ - \n- pipeline ', + \n- pipeline ", Linear: - '\n- Issue \ - \n- IssueLabel', + "\n- Issue \ + \n- IssueLabel", LaunchDarkly: - '\n- flag \ + "\n- flag \ \n- environment \ \n- project \ - \n- auditlog', + \n- auditlog", Octopus: - '\n- spaces \ + "\n- spaces \ \n- projects \ \n- deployments \ \n- releases \ - \n- machines', + \n- machines", NewRelic: - '**Issues:** \ + "**Issues:** \ \n- issue_created \ \n- issue_updated \ - \n- issue_closed', + \n- issue_closed", AzureDevOps: - '**Code Events:** \ + "**Code Events:** \ \n- git.pullrequest.created \ \n- git.pullrequest.updated \ - \n- git.push', - BitbucketServer: - '**Pull Request:** \ + \n- git.push", + BitbucketServer: + "**Pull Request:** \ \n- pr:modified \ \n- pr:opened \ \n- pr:merged \ @@ -186,23 +183,36 @@ export const liveEvents = { \n- repo:modified \ \n- repo:refs_changed \ \n\n**Project:** \ - \n- project:modified', + \n- project:modified", + GithubOcean: + " **Repository:** \ + \n - created \ + \n - edited \ + \n - renamed \ + \n - transferred \ + \n - unarchived \ + \n - publicized \ + \n - privatized \ + \n - archived \ + \n - deleted \ + \n\n **pull_request:** \ + \n - opened \ + \n - edited \ + \n - ready_for_review \ + \n - reopened \ + \n - synchronize \ + \n - unassigned \ + \n - review_request_removed \ + \n - closed \ + \n\n **push:** ", }; export const OceanSaasLiveEventsTriggersOAuth = ({ id, isOAuth = false }) => { - return ( - - {liveEvents[id + "_OAuth"]} - - ); + return {liveEvents[id + "_OAuth"]}; }; export const OceanSaasLiveEventsTriggersManual = ({ id, isOAuth = false }) => { - return ( - - {liveEvents[id]} - - ); + return {liveEvents[id]}; }; export const OceanSaasLiveEventsDescription = ({ id }) => { diff --git a/static/img/integrations/github-ocean/AuditLog.png b/static/img/integrations/github-ocean/AuditLog.png new file mode 100644 index 0000000000..fa6b13c96d Binary files /dev/null and b/static/img/integrations/github-ocean/AuditLog.png differ diff --git a/static/img/integrations/github-ocean/GitHubAppChooseRepos.png b/static/img/integrations/github-ocean/GitHubAppChooseRepos.png new file mode 100644 index 0000000000..f10d42fb05 Binary files /dev/null and b/static/img/integrations/github-ocean/GitHubAppChooseRepos.png differ diff --git a/static/img/integrations/github-ocean/GitHubAppInstallPage.png b/static/img/integrations/github-ocean/GitHubAppInstallPage.png new file mode 100644 index 0000000000..b3a0aeb0e1 Binary files /dev/null and b/static/img/integrations/github-ocean/GitHubAppInstallPage.png differ diff --git a/static/img/integrations/github-ocean/GitHubInstallationSuccess.png b/static/img/integrations/github-ocean/GitHubInstallationSuccess.png new file mode 100644 index 0000000000..d82b5d7998 Binary files /dev/null and b/static/img/integrations/github-ocean/GitHubInstallationSuccess.png differ diff --git a/static/img/integrations/github-ocean/SelfHosetdGeneratePrivayKey.png b/static/img/integrations/github-ocean/SelfHosetdGeneratePrivayKey.png new file mode 100644 index 0000000000..de371726c7 Binary files /dev/null and b/static/img/integrations/github-ocean/SelfHosetdGeneratePrivayKey.png differ diff --git a/static/img/integrations/github-ocean/SelfHostedEditGitHubApp.png b/static/img/integrations/github-ocean/SelfHostedEditGitHubApp.png new file mode 100644 index 0000000000..60c901308e Binary files /dev/null and b/static/img/integrations/github-ocean/SelfHostedEditGitHubApp.png differ diff --git a/static/img/integrations/github-ocean/SelfHostedInstallationRepoSelection.png b/static/img/integrations/github-ocean/SelfHostedInstallationRepoSelection.png new file mode 100644 index 0000000000..ae62a56563 Binary files /dev/null and b/static/img/integrations/github-ocean/SelfHostedInstallationRepoSelection.png differ diff --git a/static/img/integrations/github-ocean/SelfHostedNewGitHubApp.png b/static/img/integrations/github-ocean/SelfHostedNewGitHubApp.png new file mode 100644 index 0000000000..40174ec26f Binary files /dev/null and b/static/img/integrations/github-ocean/SelfHostedNewGitHubApp.png differ diff --git a/static/img/integrations/github-ocean/SelfHostedOrganizaionView.png b/static/img/integrations/github-ocean/SelfHostedOrganizaionView.png new file mode 100644 index 0000000000..8cb8a75ea1 Binary files /dev/null and b/static/img/integrations/github-ocean/SelfHostedOrganizaionView.png differ diff --git a/static/img/integrations/github-ocean/SelfHostedOrganizationSettings.png b/static/img/integrations/github-ocean/SelfHostedOrganizationSettings.png new file mode 100644 index 0000000000..9325771c38 Binary files /dev/null and b/static/img/integrations/github-ocean/SelfHostedOrganizationSettings.png differ