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 Ocean",
+  "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,17 @@
+- [`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)
+- [`environment`](https://docs.github.com/en/rest/deployments/environments#get-an-environment)
+- [`deployment`](https://docs.github.com/en/rest/deployments/deployments#get-a-deployment)
+- [`workflow`](https://docs.github.com/en/rest/actions/workflows#get-a-workflow)
+- [`workflow-run`](https://docs.github.com/en/rest/actions/workflow-runs#get-a-workflow-run)
+- [`issue`](https://docs.github.com/en/rest/issues/issues#get-an-issue)
+- [`folder`](https://docs.github.com/en/rest/git/trees#get-a-tree)
+- [`file`](/build-your-software-catalog/sync-data-to-catalog/git/github/#ingest-files-from-your-repositories)
+- [`user`](https://docs.github.com/en/rest/users/users#get-a-user)
+- [`team`](https://docs.github.com/en/rest/teams/teams#get-a-team-by-name)
+- [`dependabot-alert`](https://docs.github.com/en/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository)
+- [`branches`](https://docs.github.com/en/rest/branches/branches#get-a-branch)
+- [`code-scanning`](https://docs.github.com/en/rest/code-scanning/code-scanning#list-code-scanning-alerts-for-a-repository)
+- [`releases`](https://docs.github.com/en/rest/releases/releases#list-releases)
+- [`tags`](https://docs.github.com/en/rest/repos/repos#list-repository-tags)
+

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/example-repository-admins/_github_export_example_repository_with_admins_relation_blueprint.mdx

@@ -0,0 +1,38 @@
+<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"
+      }
+    },
+    "required": []
+  },
+  "mirrorProperties": {},
+  "calculationProperties": {},
+  "aggregationProperties": {},
+  "relations": {
+    "admins": {
+      "title": "Admins",
+      "target": "githubUser",
+      "required": false,
+      "many": true
+    }
+  }
+}
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-repository-admins/_github_exporter_example_admins_users_port_app_config.mdx

@@ -0,0 +1,48 @@
+<details>
+
+<summary> Port port-app-config.yml </summary>
+
+```yaml showLineNumbers
+createMissingRelatedEntities: true
+resources:
+  - kind: repository
+    selector:
+      query: "true"
+      collaborators: true
+    port:
+      entity:
+        mappings:
+          identifier: .name
+          title: .name
+          blueprint: '"githubRepository"'
+          properties:
+            readme: file://README.md
+            url: .html_url
+            defaultBranch: .default_branch
+          relations:
+            admins: "[.collaborators[] | select(.is_admin == true) | .login]"
+  - kind: user
+    selector:
+      query: "true"
+    port:
+      entity:
+        mappings:
+          identifier: .login
+          title: .login
+          blueprint: '"githubUser"'
+          relations:
+            user: .email
+  - kind: user
+    selector:
+      query: "true"
+    port:
+      entity:
+        mappings:
+          identifier: .email
+          title: .email
+          blueprint: '"user"'
+          relations:
+            user: .email
+```
+
+</details>

docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-repository-admins/_github_exporter_example_github_users_blueprint.mdx

@@ -0,0 +1,32 @@
+<details>
+<summary>Github Users blueprint</summary>
+
+```json showLineNumbers
+{
+  "identifier": "githubUser",
+  "title": "Github User",
+  "icon": "Microservice",
+  "schema": {
+    "properties": {
+      "email": {
+         "title": "Email",
+         "type": "string"
+      }
+    },
+    "required": []
+  },
+  "mirrorProperties": {},
+  "calculationProperties": {},
+  "aggregationProperties": {},
+  "relations": {
+    "user": {
+      "title": "User",
+      "target": "user",
+      "required": false,
+      "many": false
+    }
+  }
+}
+```
+
+</details>