> For the complete documentation index, see llms.txt.
Skip to main content

Check out Port for yourself ➜ 

GitHub workflow via Ocean

The GitHub Ocean backend allows you to trigger GitHub workflows for your self-service actions and automations, using the GitHub Ocean integration.

Integration-based backend

The GitHub Ocean backend uses the INTEGRATION_ACTION type and requires you to specify which GitHub Ocean integration installation to use via the installationId field.

Prerequisites​

Before using the GitHub Ocean backend, you need to:

  1. Install the GitHub Ocean integration in your Port organization.
  2. Ensure that actions processing is enabled:
  3. Ensure the integration uses Port machine tokens (organization-level tokens). Personal tokens or service account tokens are not supported.
Terraform provider minimum version

To manage self-service actions with the GitHub Ocean (INTEGRATION_ACTION) backend via Terraform, you need Port Terraform provider v2.19.5 or later. Earlier versions do not support the INTEGRATION_ACTION invocation type. Update your provider version constraint if you are migrating actions from the legacy GitHub App backend:

terraform {
  required_providers {
    port = {
      source  = "port-labs/port-labs"
      version = ">= 2.19.5"
    }
  }
}

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:

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

When using this backend, you need to provide:

  • The integration installation ID (installationId) - specifies which GitHub Ocean integration instance to use.
  • The GitHub organization and repository where the workflow is located.
  • The workflow name.
  • The integration action type (integrationActionType) - must be set to dispatch_workflow.

Important notes:

  • The workflow must reside in the repository's .github/workflows/ directory.
  • The workflow must use the workflow_dispatch trigger.
    For example, see the workflow implementation in this guide.

Automatic workflow status update​

Additionally, you can define whether or not Port should automatically use the workflow's end status (SUCCESS/FAILURE) to update the action/automation status in Port.

By default, this is set to true. To disable this option, set the reportWorkflowStatus field to false in the invocationMethod object, or turn the Report workflow status toggle off if using the UI.

Live events requirement

To enable automatic workflow status updates, the integration must have live events enabled. Workflow status is updated via webhook events from GitHub. Live events are automatically enabled for integrations hosted by Port, but must be manually configured for self-hosted installations.

Organization auto-fill​

The org field behavior depends on the installation type:

  • If the integration is hosted by Port, the org input field will be hidden and prefilled in the UI. Port automatically knows which organization you selected during installation.
  • If the integration is self-hosted, you must always fill in the organization input, even if it is configured for a specific organization.
  • When creating an action through the API, you must specify the organization even if the integration is hosted by Port.

Specify a branch​

By default, the integration will look for the workflow in the repository's default branch (usually main/master).

To use a different branch, simply pass the ref key in the Configure the invocation payload section (or invocationMethod.workflowInputs in the JSON object) with the desired branch name as the value:

{
  "ref": "my-branch-name"
}
Workflow file must exist in the default branch

Due to GitHub's behavior, to trigger a workflow that uses the workflow_dispatch event from a non-default branch using the ref key, the same workflow file must exist in the default branch.

TIP: If you prefer not to include the full workflow file in the default branch, placing a workflow file with the same name is enough for the correct workflow in the non-branch to run successfully.

Limitations​

Input limit​

A GitHub workflow can have up to 10 input parameters. Note this when defining your payloads.
If you need more than 10 inputs, you can use a JSON object as a single parameter.

Workflow chains​

A workflow triggered using the workflow_dispatch trigger is self-contained. This means its actions and effects over the repository cannot trigger other automatic workflows.

For example, take the following scenario:

  1. A developer executes a "Create a new microservice in a monorepo" workflow.
  2. The workflow opens a new pull request in the target repository based on a pre-defined template.
  3. The repository also has a workflow which is automatically triggered using the on: pull_request: types: "opened" trigger.
  4. In this instance, the automatic PR workflow will not be triggered.