GitHub integration action

The GitHub integration action allows workflows to trigger GitHub Actions workflows directly using your installed GitHub integration.

Prerequisites

• A GitHub integration installed in your Port organization.
• The GitHub Actions workflow you want to trigger must exist in the target repository.
• The workflow must be configured to accept workflow_dispatch events.
• Actions processing must be enabled on your integration:
  • Hosted by Port / UI / OAuth installations: actions processing is enabled automatically.
  • Self-hosted (Helm or Docker): actions processing is disabled by default and must be explicitly enabled. See Enable actions processing for self-hosted installations below.

Enable actions processing for self-hosted installations

If you installed the GitHub Ocean integration as hosted by Port (via the UI or OAuth), actions processing is enabled automatically and you can skip to Configuration.

For self-hosted deployments (Kubernetes/Helm or Docker), the actions processor is disabled by default. You need to enable it explicitly using the flags below, depending on how you deployed the integration:

Helm

Pass the following flags when installing or upgrading the Helm chart:

helm upgrade --install github-ocean port-labs/port-ocean \
  --set actionsProcessor.enabled=true \
  --set ocean.baseUrl=<YOUR_INTEGRATION_BASE_URL> \
  # ... rest of your values

• actionsProcessor.enabled=true - enables the actions processor so the integration can receive and execute GitHub Actions dispatch requests from Port.
• ocean.baseUrl=<YOUR_INTEGRATION_BASE_URL> - required when reportWorkflowStatus is enabled (the default). Port uses this URL to receive webhook events from GitHub and update the action run status in real time. The URL must be reachable from GitHub.

Docker

Add the following environment variables to your Docker run command or docker-compose configuration:

docker run \
  -e OCEAN__FEATURE_FLAGS__ACTIONS_PROCESSOR_ENABLED=true \
  -e OCEAN__INTEGRATION__CONFIG__OCEAN_BASE_URL=<YOUR_INTEGRATION_BASE_URL> \
  # ... rest of your env vars
  ghcr.io/port-labs/port-ocean-github:latest

What is reportWorkflowStatus?

By default, Port automatically updates the action/automation run status in Port when the triggered GitHub workflow finishes. This requires GitHub to send a webhook event back to the integration. If the integration's base URL is not set, Port cannot receive this callback and the run status will not be updated automatically.

To disable this behavior, set reportWorkflowStatus: false in the invocationMethod of your action, or turn off the Report workflow status toggle in the UI.

If you disable automatic reporting, add a step in your GitHub workflow that uses port-labs/port-github-action@v1 with the PATCH_RUN operation to update the action run status in Port. See Port's GitHub action for configuration details.

Configuration

Field	Type	Description
type	"INTEGRATION_ACTION"	Required. Must be "INTEGRATION_ACTION"
installationId	string	Required. Your GitHub integration installation ID
integrationProvider	"github-ocean"	Required. Must be "github-ocean"
integrationInvocationType	"dispatch_workflow"	Required. Operation type
integrationActionExecutionProperties	object	Required. GitHub-specific configuration

Execution properties

Field	Type	Description
org	string	Required. GitHub organization or user name (e.g., port-labs)
repo	string	Required. Repository name (e.g., my-repo)
workflow	string	Required. Workflow filename (e.g., deploy.yml) or workflow ID
workflowInputs	object	Input parameters to pass to the workflow
reportWorkflowStatus	boolean	Whether to report workflow status back to Port

Basic example

Trigger a GitHub actions deployment workflow, passing environment and version from the trigger inputs:

{
  "identifier": "trigger-github-workflow",
  "title": "Trigger GitHub Deployment",
  "config": {
    "type": "INTEGRATION_ACTION",
    "installationId": "your-installation-id",
    "integrationProvider": "github-ocean",
    "integrationInvocationType": "dispatch_workflow",
    "integrationActionExecutionProperties": {
      "org": "my-org",
      "repo": "{{ .outputs.trigger.repository }}",
      "workflow": "deploy.yml",
      "workflowInputs": {
        "environment": "{{ .outputs.trigger.environment }}",
        "version": "{{ .outputs.trigger.version }}"
      }
    }
  }
}

Workflow inputs

Pass inputs to your GitHub Actions workflow:

{
  "integrationActionExecutionProperties": {
    "org": "my-org",
    "repo": "my-repo",
    "workflow": "build-and-deploy.yml",
    "workflowInputs": {
      "environment": "{{ .outputs.trigger.environment }}",
      "version": "{{ .outputs.trigger.version }}",
      "dry_run": "{{ .outputs.trigger.dryRun | tostring }}"
    }
  }
}

String inputs

GitHub Actions workflow inputs are always strings. Use JQ functions like tostring to convert non-string values.

Status reporting

Enable reportWorkflowStatus to have the GitHub workflow report its status back to Port:

{
  "integrationActionExecutionProperties": {
    "org": "my-org",
    "repo": "my-repo",
    "workflow": "deploy.yml",
    "workflowInputs": {
      "environment": "{{ .outputs.trigger.environment }}"
    },
    "reportWorkflowStatus": true
  }
}

When enabled, Port will monitor the GitHub workflow run and update the node status when it completes.

Complete workflow example

A self-service deployment workflow that triggers GitHub Actions, waits for completion, and updates the service entity with deployment details:

Workflow example (click to expand)

{
  "identifier": "deploy-with-github",
  "title": "Deploy Service with GitHub Actions",
  "icon": "Github",
  "description": "Trigger a deployment using GitHub Actions",
  "nodes": [
    {
      "identifier": "trigger",
      "title": "Request Deployment",
      "config": {
        "type": "SELF_SERVE_TRIGGER",
        "userInputs": {
          "properties": {
            "service": {
              "type": "string",
              "format": "entity",
              "blueprint": "service",
              "title": "Service"
            },
            "environment": {
              "type": "string",
              "title": "Environment",
              "enum": ["staging", "production"]
            },
            "version": {
              "type": "string",
              "title": "Version",
              "description": "Git tag or commit SHA"
            }
          },
          "required": ["service", "environment", "version"]
        }
      }
    },
    {
      "identifier": "trigger-deploy",
      "title": "Trigger GitHub Deployment",
      "config": {
        "type": "INTEGRATION_ACTION",
        "installationId": "gh-integration-123",
        "integrationProvider": "github-ocean",
        "integrationInvocationType": "dispatch_workflow",
        "integrationActionExecutionProperties": {
          "org": "my-org",
          "repo": "{{ .outputs.trigger.service }}",
          "workflow": "deploy.yml",
          "workflowInputs": {
            "environment": "{{ .outputs.trigger.environment }}",
            "version": "{{ .outputs.trigger.version }}"
          },
          "reportWorkflowStatus": true
        }
      }
    },
    {
      "identifier": "update-entity",
      "title": "Update Service Status",
      "config": {
        "type": "UPSERT_ENTITY",
        "blueprintIdentifier": "service",
        "mapping": {
          "identifier": "{{ .outputs.trigger.service }}",
          "properties": {
            "lastDeployedVersion": "{{ .outputs.trigger.version }}",
            "lastDeployedEnvironment": "{{ .outputs.trigger.environment }}",
            "lastDeployedAt": "{{ now | todateiso8601 }}"
          }
        }
      }
    }
  ],
  "connections": [
    {
      "sourceIdentifier": "trigger",
      "targetIdentifier": "trigger-deploy"
    },
    {
      "sourceIdentifier": "trigger-deploy",
      "targetIdentifier": "update-entity"
    }
  ]
}

GitHub workflow configuration

Your GitHub actions workflow must be configured to accept workflow_dispatch:

GitHub Actions workflow (click to expand)

# .github/workflows/deploy.yml
name: Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        type: choice
        options:
          - staging
          - production
      version:
        description: 'Version to deploy'
        required: true
        type: string
      triggered_by:
        description: 'User who triggered the deployment'
        required: false
        type: string

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.version }}
      
      - name: Deploy to ${{ inputs.environment }}
        run: |
          echo "Deploying version ${{ inputs.version }} to ${{ inputs.environment }}"
          echo "Triggered by: ${{ inputs.triggered_by }}"
          # Your deployment logic here