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 an access token to give the integration permissions to query your Github organization.
- How to deploy 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โ
Create 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)
- GitHub App
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.
- The token must belong to a user with access to the relevant Github resources (e.g., repositories, teams).
Required permissions
These are the necessary permissions if you're creating a fine-grained PAT.
Repository permissions:
- Content: Readonly
- Metadata: Readonly
- Pull Requests: Readonly
Organization permissions:
- Webhooks: Read and Write (for managing webhook)
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.
A GitHub App provides automatic access token rotation and is a good alternative to PATs.
To set it up, see the GitHub App installation guide.
Deploy the integrationโ
To deploy the integration, you will need your Port CLIENT_ID
and CLIENT_SECRET
.
To get your Port credentials, go to your Port application, click on the ...
button in the top right corner, and select Credentials
. Here you can view and copy your CLIENT_ID
and CLIENT_SECRET
:

Choose the installation method that best suits your needs:
- Kubernetes
- Docker
- Scheduled (CI)
Using this installation option means that the integration will be able to update Port in real time using webhooks.
Prerequisites
To install the integration, you need a Kubernetes cluster that the integration's container chart will be deployed to.
Please make sure that you have kubectl
and helm
installed on your machine, and that your kubectl
CLI is connected to the Kubernetes cluster where you plan to install the integration.
If you are having trouble installing this integration, please refer to these troubleshooting steps.
For details about the available parameters for the installation, see the table below.
- Helm
- ArgoCD
To install the integration using Helm:
Add Port's Helm chart repository:
helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
Install the Helm chart:
- Create a
values.yaml
file with the following content:
port:
clientId: "<PORT_CLIENT_ID>"
clientSecret: "<PORT_CLIENT_SECRET>"
baseUrl: "https://api.port.io"
integration:
identifier: "github-ocean"
type: "github-ocean"
version: "1.2.0-beta"
eventListener:
type: "POLLING"
config:
githubOrganization: "<GITHUB_ORGANIZATION>"
githubHost: "<GITHUB_HOST>" # e.g https://api.github.com
secrets:
githubToken: "<GITHUB_PAT>"
# uncomment to enable live events
# liveEvents:
# baseUrl: "<your-domain>"
initializePortResources: true
sendRawDataExamples: true
scheduledResyncInterval: 360
- Install the Helm chart using the
values.yaml
file:
helm upgrade --install github-ocean port-labs/port-ocean -f values.yaml
See all available helm options
The port_region
, port.baseUrl
, portBaseUrl
, port_base_url
and OCEAN__PORT__BASE_URL
parameters are used to select which instance or Port API will be used.
Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.
- If you use the EU region of Port (https://app.port.io), your API URL is
https://api.port.io
. - If you use the US region of Port (https://app.us.port.io), your API URL is
https://api.us.port.io
.
To install the integration using ArgoCD:
- Create a
values.yaml
file inargocd/my-ocean-github-integration
in your git repository with the content:
Be sure to replace the <GITHUB_TOKEN>
and <GITHUB_ORGANIZATION>
placeholders with your actual values. If you are using a self-hosted GitHub instance, update the githubHost
value to point to your instance.
initializePortResources: true
scheduledResyncInterval: 120
integration:
identifier: my-ocean-github-integration
type: github-ocean
version: 1.2.0-beta
eventListener:
type: POLLING
config:
githubHost: https://api.github.com # Or your self-hosted GitHub URL
githubOrganization: "<GITHUB_ORGANIZATION>" # your github organization, e.g port-labs
secrets:
githubToken: "<GITHUB_TOKEN>"
# uncomment to enable live events
# liveEvents:
# baseUrl: "<your-domain>"
- Install the
my-ocean-github-integration
ArgoCD Application by creating the followingmy-ocean-github-integration.yaml
manifest:
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.
ArgoCD Application
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.9.5
helm:
valueFiles:
- $values/argocd/my-ocean-github-integration/values.yaml
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>
targetRevision: main
ref: values
syncPolicy:
automated:
prune: true
selfHeal: true
syncOptions:
- CreateNamespace=true
The port_region
, port.baseUrl
, portBaseUrl
, port_base_url
and OCEAN__PORT__BASE_URL
parameters are used to select which instance or Port API will be used.
Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.
- If you use the EU region of Port (https://app.port.io), your API URL is
https://api.port.io
. - If you use the US region of Port (https://app.us.port.io), your API URL is
https://api.us.port.io
.
- Apply your application manifest with
kubectl
:
kubectl apply -f my-ocean-github-integration.yaml
Enabling live-eventsโ
The liveEvents.baseUrl
parameter is used specifically to enable the real-time functionality of the integration.
For debugging, services like Ngrok can provide a temporary public URL. For production, a stable and publicly accessible host is required.
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
parameter has to be set, or a manual resync will need to be triggered through Port's UI.
This integration supports live events, allowing real-time updates to your software catalog without waiting for the next scheduled sync.
The Repository: pull_request: pushliveEvents.baseUrl
specifies the public-facing URL for your integration. This URL, which must be reachable from the internet, is used to receive real-time updates from Github. It can be a public IP address or a configured domain name (e.g., https://mygithubintegration.com
).Supported live event triggers
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 API endpoint for your GitHub instance. For GitHub Enterprise Cloud, this will be https://api.<SUBDOMAIN>.ghe.com . Defaults to https://api.github.com if not provided. | โ |
integration.secrets.githubToken | A GitHub Personal Access Token (PAT) to authenticate with your GitHub Organization. Only required when you're not authenticating as a Github app | โ |
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. | โ |
liveEvents.baseUrl | The base url of the instance where the GitHub integration is hosted, used for real-time updates (e.g. https://mygithuboceanintegration.com ). | โ |
integration.config.webhookSecret | A secret to secure webhooks from GitHub. This is optional but highly recommended for security if you enable live-events. | โ |
For advanced configuration such as proxies or self-signed certificates, click here.
Our integration can be directly run as a docker container, 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:
docker pull ghcr.io/port-labs/port-ocean-github-ocean:1.2.0-beta
Run the following command to start the app:
docker run \
-e OCEAN__PORT__CLIENT_ID="<PORT_CLIENT_ID>" \
-e OCEAN__PORT__CLIENT_SECRET="<PORT_CLIENT_SECRET>" \
-e OCEAN__PORT__BASE_URL="https://api.getport.io" \
-e OCEAN__BASE_URL="<https.example.com>" \ #optional, only required if you want to enable live-events
-e OCEAN__EVENT_LISTENER__TYPE="POLLING" \
-e OCEAN__INTEGRATION__CONFIG__GITHUB_HOST="<GITHUB_HOST>" \ # e.g https://api.github.com
-e OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION="<GITHUB_ORGANIZATION>" \
-e OCEAN__INTEGRATION__IDENTIFIER="github-ocean" \
-e OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN="<GITHUB_TOKEN>" \
-p 8000:8000 \
ghcr.io/port-labs/port-ocean-github-ocean:1.2.0-beta
The command above contains placeholder values in angle brackets (e.g., <PORT_CLIENT_ID>
). Be sure to replace them with your actual values before running the command.
Env variable | Description | Required |
---|---|---|
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__PORT__BASE_URL | Port's API Base URL | โ |
OCEAN__BASE_URL | The base url of the instance where the GitHub integration is hosted, used for real-time updates (e.g. https://mygithuboceanintegration.com ). | โ |
OCEAN__INTEGRATION__CONFIG__WEBHOOK_SECRET | A secret to secure webhooks from GitHub. This is optional but highly recommended for security if you enable live-events. | โ |
OCEAN__EVENT_LISTENER__TYPE | Define the appropriate event listener type to handle incoming events and resync requests from Port. This listener will forward the events to the GitHub Ocean integration. For more details, see the Port Event Listener documentation | โ |
OCEAN__INTEGRATION__CONFIG__GITHUB_HOST | The API endpoint for your GitHub instance. For GitHub Enterprise, this will be https://api.<SUBDOMAIN>.ghe.com . Defaults to https://api.github.com if not provided. | โ |
OCEAN__INTEGRATION__CONFIG__GITHUB_ORGANIZATION | The GitHub organization the integration was installed in. | โ |
OCEAN__INTEGRATION__IDENTIFIER | A unique identifier for the integration instance. Useful if you are running multiple self-hosted GitHub integrations. Defaults to github-ocean . | โ |
OCEAN__INTEGRATION__CONFIG__GITHUB_TOKEN | Github PAT. | โ |
The port_region
, port.baseUrl
, portBaseUrl
, port_base_url
and OCEAN__PORT__BASE_URL
parameters are used to select which instance or Port API will be used.
Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.
- If you use the EU region of Port (https://app.port.io), your API URL is
https://api.port.io
. - If you use the US region of Port (https://app.us.port.io), your API URL is
https://api.us.port.io
.
This workflow/pipeline will run the GitHub integration once and then exit. This is useful for scheduled ingestion of data.
If you want the integration to update Port in real time using webhooks you should use the Kubernetes or Docker installation options.
- GitHub
- Jenkins
- Azure Devops
- GitLab
Make sure to configure the following Github Secrets:
Parameter | Description | Example | Required |
---|---|---|---|
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 | โ | |
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. | โ | |
OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION | The name of your Github organization | โ | |
OCEAN__PORT__CLIENT_ID | Your Port client (How to get the credentials) id | โ | |
OCEAN__PORT__CLIENT_SECRET | Your Port client (How to get the 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 | โ | |
OCEAN__INTEGRATION__IDENTIFIER | The identifier of the integration that will be installed | โ |
Here is an example for a github-integration.yml
workflow file:
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 }}
Your Jenkins agent should be able to run docker commands.
Make sure to configure the following Jenkins Credentials
of Secret Text
type:
Parameter | Description | Example | Required |
---|---|---|---|
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 | โ | |
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. | โ | |
OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION | The name of your Github organization | โ | |
OCEAN__PORT__CLIENT_ID | Your Port client (How to get the credentials) id | โ | |
OCEAN__PORT__CLIENT_SECRET | Your Port client (How to get the 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 | โ | |
OCEAN__INTEGRATION__IDENTIFIER | The identifier of the integration that will be installed | โ |
Here is an example for a Jenkinsfile
groovy pipeline file:
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="1.2.0-beta"
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:
Parameter | Description | Example | Required |
---|---|---|---|
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 | โ | |
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. | โ | |
OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION | The name of your Github organization | โ | |
OCEAN__PORT__CLIENT_ID | Your Port client (How to get the credentials) id | โ | |
OCEAN__PORT__CLIENT_SECRET | Your Port client (How to get the 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 | โ | |
OCEAN__INTEGRATION__IDENTIFIER | The identifier of the integration that will be installed | โ |
Here is an example for a github-integration.yml
pipeline file:
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="1.2.0-beta"
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:
Parameter | Description | Example | Required |
---|---|---|---|
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 | โ | |
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. | โ | |
OCEAN__INTEGRATION__CONFIG__GTIHUB_ORGANIZATION | The name of your Github organization | โ | |
OCEAN__PORT__CLIENT_ID | Your Port client (How to get the credentials) id | โ | |
OCEAN__PORT__CLIENT_SECRET | Your Port client (How to get the 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 | โ | |
OCEAN__INTEGRATION__IDENTIFIER | The identifier of the integration that will be installed | โ |
Here is an example for a .gitlab-ci.yml
pipeline file:
default:
image: docker:24.0.5
services:
- docker:24.0.5-dind
before_script:
- docker info
variables:
INTEGRATION_TYPE: github-ocean
VERSION: 1.2.0-beta
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
The port_region
, port.baseUrl
, portBaseUrl
, port_base_url
and OCEAN__PORT__BASE_URL
parameters are used to select which instance or Port API will be used.
Port exposes two API instances, one for the EU region of Port, and one for the US region of Port.
- If you use the EU region of Port (https://app.port.io), your API URL is
https://api.port.io
. - If you use the US region of Port (https://app.us.port.io), your API URL is
https://api.us.port.io
.
For advanced configuration such as proxies or self-signed certificates, click here.