Skip to content

Commit 629cfd4

Browse files
sivanel97sivanel97
authored
Merge pull request #2885 from port-labs/PORT-16573
Add Multi Org Support Section for GitHub Ocean
2 parents 6f9a671 + c4e02b4 commit 629cfd4

17 files changed

+351
-28
lines changed

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_docker_parameters.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
| Parameter | Description | Example | Required |
22
| --------- | ----------- | ------- | -------- |
3-
| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ |
3+
| `OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN` | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Use classic PAT for multi-org support (v3.0.0-beta+). Only required when you're not authenticating as a [Github app](./installation/github-app.mdx) | | ✅ |
44
| `OCEAN__INTEGRATION__CONFIG__GTIHUB_HOST` | The API endpoint for your GitHub instance. For GitHub Enterprise Cloud, this will be `https://<org_name.ghe.com>`. Defaults to `https://api.github.com` if not provided. | | ❌ |
5-
| `OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION` | The name of your Github organization | | ✅ |
5+
| `OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION` | The name of your Github organization (for GitHub App or Fine-grained PAT authentication). Required for single-org authentication. | | ❌ |
66
| `OCEAN__PORT__CLIENT_ID` | Your Port client id([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ |
77
| `OCEAN__PORT__CLIENT_SECRET` | Your Port client secret ([How to get the credentials](https://docs.port.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | | ✅ |
88
| `OCEAN__PORT__BASE_URL` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ |

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/_github_exporter_supported_resources.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
- [`organization`](https://docs.github.com/en/rest/orgs/orgs?apiVersion=2022-11-28#list-organizations-for-the-authenticated-user)
12
- [`repository`](https://docs.github.com/en/rest/repos/repos#get-a-repository)
23
- [`pull-request`](https://docs.github.com/en/rest/pulls/pulls#get-a-pull-request)
34
- [`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/_github_exporter_example_port_app_config.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,8 @@ resources:
1717
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
1818
url: .html_url
1919
defaultBranch: .default_branch
20+
relations:
21+
organization: .__organization.login
2022
- kind: pull-request
2123
selector:
2224
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.

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

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,14 @@
2727
},
2828
"mirrorProperties": {},
2929
"calculationProperties": {},
30-
"relations": {}
30+
"relations": {
31+
"organization": {
32+
"title": "Organization",
33+
"target": "githubOrganization",
34+
"required": false,
35+
"many": false
36+
}
37+
}
3138
}
3239
```
3340

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,10 @@ resources:
2525
query: 'true'
2626
files:
2727
- path: 'README.md'
28+
organization: my-org # Optional if githubOrganization is set; required if not set
2829
repos:
2930
- name: test-repo
31+
branch: main
3032
port:
3133
entity:
3234
mappings:

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
query: 'true'
99
files:
1010
- path: '**/package.json'
11+
organization: my-org # Optional if githubOrganization is set; required if not set
1112
repos:
1213
- name: vscode
1314
branch: main

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-monorepo/_github_exporter_example_monorepo_port_app_config.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ resources:
99
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
1010
folders: # Specify the repositories and folders to include under this relative path.
1111
- path: apps/* # Relative path to the folders within the repositories.
12+
organization: my-org # Optional if githubOrganization is set; required if not set
1213
repos: # List of repositories to include folders from.
1314
- name: backend-service
1415
branch: main

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_blueprint.mdx‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<details>
2+
<summary><b>Organization blueprint (click to expand)</b></summary>
3+
4+
```json showLineNumbers
5+
{
6+
"identifier": "githubOrganization",
7+
"description": "This blueprint represents a service in our software catalog",
8+
"title": "Organization",
9+
"icon": "Github",
10+
"schema": {
11+
"properties": {
12+
"login": {
13+
"type": "string",
14+
"title": "Organization Login",
15+
"description": "The GitHub organization login name"
16+
},
17+
"id": {
18+
"type": "number",
19+
"title": "Organization ID",
20+
"description": "GitHub organization ID"
21+
},
22+
"nodeId": {
23+
"type": "string",
24+
"title": "Node ID",
25+
"description": "GitHub GraphQL node ID"
26+
},
27+
"url": {
28+
"type": "string",
29+
"title": "API URL",
30+
"description": "GitHub API URL for the organization"
31+
},
32+
"reposUrl": {
33+
"type": "string",
34+
"title": "Repositories URL",
35+
"description": "URL to organization's repositories"
36+
},
37+
"eventsUrl": {
38+
"type": "string",
39+
"title": "Events URL",
40+
"description": "URL to organization's events"
41+
},
42+
"hooksUrl": {
43+
"type": "string",
44+
"title": "Webhooks URL",
45+
"description": "URL to organization's webhooks"
46+
},
47+
"issuesUrl": {
48+
"type": "string",
49+
"title": "Issues URL",
50+
"description": "URL to organization's issues"
51+
},
52+
"membersUrl": {
53+
"type": "string",
54+
"title": "Members URL",
55+
"description": "URL to organization's members"
56+
},
57+
"publicMembersUrl": {
58+
"type": "string",
59+
"title": "Public Members URL",
60+
"description": "URL to organization's public members"
61+
},
62+
"avatarUrl": {
63+
"type": "string",
64+
"title": "Avatar URL",
65+
"description": "Organization avatar image URL"
66+
},
67+
"description": {
68+
"type": "string",
69+
"title": "Description",
70+
"description": "Organization description"
71+
}
72+
},
73+
"required": []
74+
},
75+
"mirrorProperties": {},
76+
"calculationProperties": {},
77+
"aggregationProperties": {},
78+
"relations": {}
79+
}
80+
```
81+
82+
</details>
83+

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/example-organization/_github_exporter_example_organization_port_app_config.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
<details>
2+
3+
<summary><b>Port port-app-config.yml (click to expand)</b></summary>
4+
5+
```yaml showLineNumbers
6+
resources:
7+
- kind: organization
8+
selector:
9+
query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
10+
port:
11+
entity:
12+
mappings:
13+
identifier: .login
14+
title: .name
15+
blueprint: '"githubOrganization"'
16+
properties:
17+
url: .html_url
18+
description: .description
19+
repositories: .public_repos
20+
createdAt: .created_at
21+
- kind: repository
22+
selector:
23+
query: "true"
24+
port:
25+
entity:
26+
mappings:
27+
identifier: .name
28+
title: .name
29+
blueprint: '"githubRepository"'
30+
properties:
31+
readme: file://README.md
32+
url: .html_url
33+
defaultBranch: .default_branch
34+
relations:
35+
organization: .__organization.login
36+
```
37+
38+
</details>
39+

‎docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,9 +50,36 @@ import DependabotAlertBlueprint from './example-repository-alerts/\_github_expor
5050
import CodeScanAlertBlueprint from './example-repository-alerts/\_github_exporter_example_codeScan_alert_blueprint.mdx'
5151
import PortRepositoryDependabotAlertMappingAppConfig from './example-repository-alerts/\_github_exporter_example_repo_dependabot_port_app_config.mdx'
5252

53+
import OrganizationBlueprint from './example-organization/\_github_exporter_example_organization_blueprint.mdx'
54+
import OrganizationAppConfig from './example-organization/\_github_exporter_example_organization_port_app_config.mdx'
55+
5356

5457
# Resource mapping examples
5558

59+
## Map organizations and repositories
60+
61+
:::info Available from v3.0.0-beta
62+
The `organization` kind is available from version `v3.0.0-beta` onwards.
63+
:::
64+
65+
The following example demonstrates how to ingest your GitHub organizations and their repositories to Port.
66+
You can use the following Port blueprint definitions and `port-app-config.yml`:
67+
68+
<OrganizationBlueprint/>
69+
70+
<RepositoryBlueprint/>
71+
72+
<OrganizationAppConfig/>
73+
74+
:::tip learn more
75+
76+
- Port leverages the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to map and transform GitHub objects to Port Entities.
77+
- Click [Here](https://docs.github.com/en/rest/orgs/orgs#get-an-organization) for the GitHub organization object structure.
78+
- Click [Here](https://docs.github.com/en/rest/repos/repos#get-a-repository) for the GitHub repository object structure.
79+
80+
:::
81+
82+
After creating the blueprints and committing the `port-app-config.yml` file, you will see new entities in Port matching your organizations and their repositories. The repositories will have a relation to their parent organization.
5683

5784
## Map repositories and pull requests
5885

0 commit comments

Comments
 (0)