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 configure and customize the integration before deploying it.
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

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.

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

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

Real-time (self-hosted)
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.

Troubleshooting

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:

Go to the github-ocean data source page in your portal.
Select the Real-time and always on method:
A helm command will be displayed, with default values already filled out (e.g. your Port client ID, client secret, etc).
Copy the command, replace the placeholders with your values, then run it in your terminal to install the integration.

Selecting a Port API URL by account region

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

initializePortResources: true
scheduledResyncInterval: 120
integration:
  identifier: my-ocean-github-integration
  type: github-ocean
  eventListener:
    type: POLLING
  config:
    githubHost: https://api.github.com # Or your self-hosted GitHub URL
    githubOrganization: <your github organization>
  secrets:
    githubToken: GITHUB_TOKEN

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.

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.8.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

Selecting a Port API URL by account region

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

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

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

This workflow/pipeline will run the GitHub integration once and then exit. This is useful for scheduled ingestion of data.

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 option.

GitHub
Jenkins
Azure Devops
GitLab

Make sure to configure the following Github Secrets:

Parameter	Description	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) 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 }}

tip

Your Jenkins agent should be able to run docker commands.

Make sure to configure the following Jenkins Credentials of Secret Text type:

Parameter	Description	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) 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="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:

Parameter	Description	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) 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="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:

Parameter	Description	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) 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: 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

Selecting a Port API URL by account region

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.

Advanced integration configuration

For advanced configuration such as proxies or self-signed certificates, click here.

Prerequisites​

Setup​

Configure access token​

Personal access token (PAT)​

Github app installation​

Configure Realtime webhook events​

Deploy the integration​

Prerequisites

Prerequisites

Setup

Configure access token

Personal access token (PAT)

Github app installation

Configure Realtime webhook events

Deploy the integration