PORT-14552 - Docs for Github ocean integration

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
+}

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 | | ❌ |

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)
+

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Examples",
+  "position": 2
+}

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_port_app_config.mdx

@@ -0,0 +1,52 @@
+<details>
+
+<summary> Port port-app-config.yml </summary>
+
+```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
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_pull_request_blueprint.mdx

@@ -0,0 +1,84 @@
+<details>
+<summary>Pull request blueprint</summary>
+
+```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(\"(?<date>\\\\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
+    }
+  }
+}
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/_github_exporter_example_repository_blueprint.mdx

@@ -0,0 +1,34 @@
+<details>
+<summary>Repository blueprint</summary>
+
+```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": {}
+}
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-file-kind/_example_package_blueprint.mdx

@@ -0,0 +1,34 @@
+<details>
+<summary>Package blueprint</summary>
+
+```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": {}
+}
+```
+
+</details>

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 @@
+<details>
+
+<summary>Port config YAML</summary>
+
+```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
+```
+
+</details>

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`:
+
+<RepositoryBlueprint/>
+
+<PRBlueprint/>
+
+<PortAppConfig/>
+
+:::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: 
+
+<PackageBlueprint />
+<PackageAppConfig />
+
+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:
+
+<GitHubResources/>
+
+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.