### GitLab Integration Setup Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/gitlab.md Instructions for setting up the GitLab integration, including required permissions and token creation. It references specific installation and token creation guides. ```markdown :::info Permission Port's GitLab integration requires a group access token with the `api` scope. To create a group access token, follow the instructions in the [installation](./installation.md#creating-a-gitlab-group-access-token) guide ::: ``` -------------------------------- ### Azure Exporter Installation Command Example Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/azure/installation.md An example of the installation command for the Azure exporter, highlighting customizable parameters like `event_grid_system_topic_name` and `event_grid_event_filter_list`. ```bash # Example installation command (actual command may vary) # docker run --rm -v $(pwd)/config:/app/config --port-client-id --port-client-secret --azure-client-id --azure-client-secret --azure-tenant-id [--event-grid-system-topic-name ] [--event-grid-event-filter-list ] [--action-permissions-list ] ``` -------------------------------- ### Install Dependencies and Start Documentation Server Source: https://github.com/port-labs/port-docs/blob/main/README.md Installs project dependencies using npm and starts the Docusaurus development server for local preview. Assumes Node.js and npm are installed. ```bash # cd to the directory of the docs and run nvm install nvm use npm install npm run start ``` -------------------------------- ### GitLab CI/CD Workflow Example Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md An example of a `.gitlab-ci.yml` file for a scheduled GitLab integration, including variable definitions and stage setup. ```yaml stages: - deploy_gitlab variables: # Define non-secret variables INTEGRATION_TYPE: "gitlab" VERSION: "latest" # These variables should be set in GitLab's CI/CD variables for security # OCEAN__PORT__CLIENT_ID: $OCEAN__PORT__CLIENT_ID # OCEAN__PORT__CLIENT_SECRET: $OCEAN__PORT__CLIENT_SECRET ``` -------------------------------- ### Install Dependencies and Start Documentation Server (Manual Node.js) Source: https://github.com/port-labs/port-docs/blob/main/README.md Installs project dependencies using npm and starts the Docusaurus development server for local preview. This is for users who installed Node.js manually. ```bash # cd to the directory of the docs and run npm install npm run start ``` -------------------------------- ### OAuth Installation Flow Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation_oauth.mdx Guides users through the OAuth installation process, including connecting to the data source page and authorizing Port. ```javascript 1. Go to the {props.integration} data source page in your portal. 2. Under `Select your installation method`, choose `Hosted by Port`. 3. Click `Connect`. This will prompt you to authorize Port and install the integration with the following default settings: See the `Application settings` section below for descriptions of these settings. ``` -------------------------------- ### GitLab System Hook Configuration Example Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md Example configuration for listening to webhooks on specified GitLab groups using `tokenGroupHooksOverrideMapping`. This allows granular control over which groups and events the integration monitors. ```text {"MY_FIRST_GROUPS_TOKEN": {"groups:"{"MY_FIRST_GROUP_FULL_PATH": {"events": [CHOSEN_EVENT_TYPES]}, "MY_OTHER_GROUP_FULL_PATH": {"events": [CHOSEN_EVENT_TYPES]}}}} ``` ```text {"glpat-QXbeg-Ev9xtu5_5FsaAQ": {"groups": {"path/to/my-first-group": {"events": ["push_events", "merge_requests_events"]}, "path/to/my-other-group": {"events": ["pipelines_events"]}}} ``` -------------------------------- ### Mapping Supported Bitbucket Resources Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-app/examples.md Explains how to ingest various Bitbucket objects into Port by adapting provided examples. It guides users to consult the Bitbucket API reference for available fields and to update the `resources` array in the `port-app-config.yml` with the correct `kind` values for each resource. ```markdown import BitbucketResources from './_bitbucket_exporter_supported_resources.mdx' ## Mapping supported resources The above example shows a specific use case, but Port's Bitbucket app supports the ingestion of many other Bitbucket objects, to adapt the example above, use the Bitbucket API reference to learn about the available fields for the different supported objects: When adding the ingestion of other resources, remember to add a entry to the `resources` array and change the value provided to the `kind` key accordingly. ``` -------------------------------- ### Manage Service Deployments using GitLab and ServiceNow Guide Source: https://github.com/port-labs/port-docs/blob/main/docs/solutions/resource-self-service/setup-approval-workflows.md This guide illustrates the capability of approval workflows by demonstrating how to manage service deployments using GitLab and ServiceNow. It is part of a series of guides showcasing Port's approval workflow features. ```markdown [Manage service deployments using GitLab and ServiceNow](/guides/all/approval-workflow-for-gitlab-deployment) ``` -------------------------------- ### Create Package Blueprint Source: https://github.com/port-labs/port-docs/blob/main/__quickstart_old.md Defines a 'Package' blueprint with 'version' and 'inHouse' properties. The 'version' property is marked as required. ```json { "identifier": "package", "title": "Package", "icon": "Package", "calculationProperties": {}, "relations": {}, "schema": { "properties": { "version": { "type": "string", "title": "Version", "description": "The version of the package" }, "inHouse": { "type": "boolean", "title": "In-House?", "description": "Whether the package was developed in house" } }, "required": ["version"] } } ``` -------------------------------- ### Example Natural Language Commands for Building in Port Source: https://github.com/port-labs/port-docs/blob/main/docs/ai-interfaces/port-mcp-server/overview-and-installation.md Demonstrates how to use natural language commands with LLMs integrated with the Port MCP Server to manage and build within Port. ```markdown * Ask: "Please help me apply this guide into my Port instance - [[guide URL]]" * Ask: "I want to start managing my k8s deployments, how can we build it in Port?" * Ask: "I want a new production readiness scorecard to track the code quality and service alerts" * Ask: "Create a new self-service action in Port to scaffold a new service" ``` -------------------------------- ### Supported Resources for Bitbucket Integration Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-cloud/examples.md Lists the resources supported by the Bitbucket integration in Port. This helps users understand what data can be ingested and how to adapt examples. ```mdx import BitbucketResources from './_bitbucket_integration_supported_resources.mdx' ``` -------------------------------- ### Jira Integration Setup Source: https://github.com/port-labs/port-docs/blob/main/docs/guides/all/report-a-bug-gitlab.md Guides users on installing the Jira integration for Port to enable instant blueprints for Jira projects and issues, and data import of existing Jira Software data. ```APIDOC Jira Integration: Purpose: Enables instant blueprints for Jira projects and issues, and data import of existing Jira Software data. Installation: - Visit: https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/project-management/jira/#installation Features: - Instant Blueprints: Automatically creates blueprints for Jira projects and issues. - Data Import: Smoothly ingests existing Jira Software data into Port. ``` -------------------------------- ### Example Natural Language Queries for Port MCP Server Source: https://github.com/port-labs/port-docs/blob/main/docs/ai-interfaces/port-mcp-server/overview-and-installation.md Illustrates how users can interact with the Port MCP Server using natural language to query their software catalog. ```markdown * Ask: "Who is the owner of service X?" * Ask: "How many services do we have in production?" * Ask: "Show me all the microservices owned by the Backend team." * Ask: "What are the dependencies of the 'OrderProcessing' service?" ``` -------------------------------- ### Airbyte Local Setup Guide Source: https://github.com/port-labs/port-docs/blob/main/docs/guides/all/ingest-okta-data-via-airbyte-s3-and-webhook.md Provides instructions and considerations for setting up Airbyte locally for data ingestion. This often involves Docker or direct installation and configuration. ```md This guide will demonstrate how to ingest Okta data into Port using [Airbyte](https://airbyte.com/), [S3](https://aws.amazon.com/s3/) and a [webhook integration](https://docs.port.io/build-your-software-catalog/custom-integration/webhook/). ## Prerequisites - Ensure you have a Port account and have completed the [onboarding process](https://docs.port.io/quickstart). - This feature is part of Port's limited-access offering. To obtain the required S3 bucket, please contact our team directly via chat, [Slack](https://www.getport.io/community), or the[support site](http://support.port.io/), and we will create and manage the bucket on your behalf. - Access to an available Airbyte app (can be cloud or self-hosted) - for reference, follow the [quick start guide](https://docs.airbyte.com/using-airbyte/getting-started/oss-quickstart). - An Okta **Personal API Token** used to retrieve data. ## Data model setup ``` -------------------------------- ### Port Hosted Installation Steps Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-server/_templates/_ocean_saas_installation.mdx Steps to install an integration hosted by Port, including navigating to the data sources page, adding a new data source, selecting the integration, choosing the 'Hosted by Port' installation method, and configuring settings. ```bash 1. Go to the [Data sources](https://app.getport.io/settings/data-sources) page of your portal. 2. Click on the `+ Data source` button in the top-right corner. 3. Click on the relevant integration in the list. 4. Under `Select your installation method`, choose `Hosted by Port`. 5. Configure the `integration settings` and `application settings` as you wish (see below for details). ``` -------------------------------- ### Helm Installation with Token Mapping Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md Example of how to set the `tokenMapping` parameter during Helm installation, ensuring proper escaping of characters for the JSON string. ```bash --set integration.secrets.tokenMapping="{\"glpat-oh1YXc54pR4eofx6hYy5\": [\"**\"]}" ``` -------------------------------- ### Install Port Pulumi Provider (Go) Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/custom-integration/iac/pulumi/_pulumi_provider_base.mdx Installs the Port Pulumi provider for Go projects using the go get command. ```go go get github.com/port-labs/pulumi-port/sdk ``` -------------------------------- ### Create Notification Microservice Entity Source: https://github.com/port-labs/port-docs/blob/main/__quickstart_old.md JSON structure for defining a new microservice entity, including its identifier, title, repository URL, Slack channel, and mapped package dependencies. ```json { "identifier": "notification-microservice", "title": "Notification Service", "properties": { "repoUrl": "https://www.github.com/User/notification", "slackChannel": "#notification-service" }, "relations": { "packages": ["requests-pkg-v2-28", "sqlAlchemy_v1_4_39"] } } ``` -------------------------------- ### Download Files from S3 using AWS CLI Source: https://github.com/port-labs/port-docs/blob/main/docs/generalTemplates/_generic_data_model_setup.md This snippet demonstrates how to download files from an S3 bucket to a local folder using the AWS CLI. It requires the AWS CLI to be installed and configured with credentials. The command recursively copies all files starting with a specified prefix. ```bash aws configure aws s3 cp s3:/// ./local-folder --recursive aws s3 cp s3://org-XXX/data/abc123/ ./my_extracted_data --recursive ``` -------------------------------- ### Create Microservice Blueprint Source: https://github.com/port-labs/port-docs/blob/main/__quickstart_old.md Defines a 'Microservice' Blueprint with fields for repository URL and Slack channel. This JSON structure outlines the schema properties, including type, format, title, and description for each field. ```json { "identifier": "microservice", "title": "Microservice", "icon": "Microservice", "schema": { "properties": { "repoUrl": { "type": "string", "format": "url", "title": "Repository URL", "description": "A URL to the Git repository of the microservice" }, "slackChannel": { "type": "string", "title": "Slack Channel", "description": "The channel of the microservice\'s maintainers" } }, "required": [] }, "mirrorProperties": {}, "calculationProperties": {}, "relations": {} } ``` -------------------------------- ### Software Catalog Organization with Folders Source: https://github.com/port-labs/port-docs/blob/main/docs/guides/_implementation-guide/launch/launch.md Details how to organize resources within the software catalog using folders, allowing for categorization by persona, team, or other criteria. ```markdown Use [folders](https://docs.port.io/customize-pages-dashboards-and-plugins/page/folders) in the software catalog to organize resources by persona, team, or any other relevant criteria. ``` -------------------------------- ### Terraform IaC Examples Source: https://github.com/port-labs/port-docs/blob/main/docs/integrations-index.md Provides examples for using Terraform for Infrastructure as Code, including provider setup, managed blueprints, resource provisioning, S3 bucket lifecycle management, developer environment setup, and importing Terraform state via webhook. ```terraform # Terraform provider setup # Example: terraform.md # Terraform managed blueprint # Example: pulumi-managed-blueprint.md # Create cloud resources using IaC # Example: create-cloud-resource-using-iac.md # Terraform manage S3 buckets lifecycle # Example: s3-bucket.md # Terraform manage developer environment # Example: create-dev-env.md # Terraform no-code resource provisioning using self-service actions # Example: terraform-no-code-resource-provisioning.md # Import Terraform state using webhook # Example: packages/terraform.md ``` -------------------------------- ### Uvicorn Server Output Example Source: https://github.com/port-labs/port-docs/blob/main/docs/actions-and-automations/setup-backend/webhook/examples/__changelog-listener.md Example output shown when the FastAPI application is successfully started and running. ```bash INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) INFO:uvicorn.error:Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) INFO: Started reloader process [32362] using StatReload INFO:uvicorn.error:Started reloader process [32362] using StatReload INFO: Started server process [32364] INFO:uvicorn.error:Started server process [32364] INFO: Waiting for application startup. INFO:uvicorn.error:Waiting for application startup. INFO: Application startup complete. INFO:uvicorn.error:Application startup complete. ``` -------------------------------- ### Install Port Jira Integration Source: https://github.com/port-labs/port-docs/blob/main/documentTemplates/__guide_teamplates.md Command to install Port's Jira integration, used to connect Jira data with Github data. ```bash ``` -------------------------------- ### Map Files and Repositories Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md Illustrates the process of mapping files to their respective repositories within Port. This requires blueprints for both files and repositories, and the `port-app-config.yml` for configuration. -------------------------------- ### Template File Example Source: https://github.com/port-labs/port-docs/blob/main/documentTemplates/__guide_teamplates.md An example JSON file that can serve as a template for specific configurations or data structures within the Port actions backend. ```json { "key": "value" } ``` -------------------------------- ### Map Deployments and Environments Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/examples/examples.md Shows how to ingest deployment and environment information from repositories into Port. This involves using specific blueprints for deployments and environments, and configuring the process with `port-app-config.yml`. -------------------------------- ### Token Mapping Configuration Example Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md This example demonstrates the correct format for the `OCEAN__INTEGRATION__CONFIG__TOKEN_MAPPING` variable. It should be saved as-is without extra quotes. ```text {"glpat-QXbeg-Ev9xtu5_5FsaAQ": ["**/DevopsTeam/*Service", "**/RnDTeam/*Service"]} ``` -------------------------------- ### Manage Kubernetes Namespaces Guide Source: https://github.com/port-labs/port-docs/blob/main/docs/solutions/resource-self-service/setup-approval-workflows.md This guide illustrates the capability of approval workflows by demonstrating how to manage Kubernetes namespaces. It is part of a series of guides showcasing Port's approval workflow features. ```markdown [Manage Kubernetes namespaces](/guides/all/manage-kubernetes-namespaces) ``` -------------------------------- ### GitLab Group Access Tokens Example Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/gitlab/installation.md Illustrates how to structure GitLab accounts and the corresponding group access tokens required for mapping projects and subgroups. ```bash GitLab account . ├── microservices-group │   ├──microservice1-group │   └──microservice2-group ├── apis-group │   ├── rest-api-group │   └── graphql-api-group ``` -------------------------------- ### User Feedback: Dashboard for Platform Engineering Source: https://github.com/port-labs/port-docs/blob/main/docs/guides/_implementation-guide/launch/launch.md Describes the creation of a dashboard for the platform engineering team to track and manage user feedback, with a reference to Port's live demo. ```markdown A **dashboard** for the platform engineering team to track and handle feedback. An example of such a dashboard can be found in Port's [live demo](https://demo.getport.io/feedback_dashboard). ``` -------------------------------- ### Action Condition Example Source: https://github.com/port-labs/port-docs/blob/main/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/setup-ui-for-action.md An example of a condition to make an action available only for entities with a specific property value. This uses Port's search and query syntax. ```json { "type": "SEARCH", "rules": [ { "operator": "=", "property": "environment", "value": "production" } ], "combinator": "and" } ``` -------------------------------- ### Provision Cloud Resource using Terraform Guide Source: https://github.com/port-labs/port-docs/blob/main/docs/solutions/resource-self-service/setup-approval-workflows.md This guide illustrates the capability of approval workflows by demonstrating how to provision a cloud resource using Terraform. It is part of a series of guides showcasing Port's approval workflow features. ```markdown [Provision Cloud Resource using Terraform](/guides/all/terraform-plan-and-apply-aws-resource) ``` -------------------------------- ### Map Repositories, Deployments, and Environments to Port Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/github/examples/examples.md Demonstrates ingesting GitHub repositories, their deployments, and environments into Port. Requires RepositoryBlueprint, RepoEnvironmentBlueprint, DeploymentBlueprint, and PortRepoDeploymentAndEnvironmentAppConfig. ```yaml kind: repository # ... blueprint definition ... kind: environment # ... blueprint definition ... kind: deployment # ... blueprint definition ... # port-app-config.yml integration: github sync: - kind: repository selector: query: "true" - kind: environment selector: query: "true" repos: ["*"] - kind: deployment selector: query: "true" repos: ["*"] ``` -------------------------------- ### Install GitHub App and Select Repositories Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/github-ocean/installation/github-app.mdx Steps to install the created GitHub App into your organization and choose specific repositories for integration. ```markdown 1. First, navigate to your organization and click on Settings: ![Org view](../../../../../../static/img/integrations/github-ocean/SelfHostedOrganizaionView.png) 2. Inside the settings view, click on Developer Settings -> and then select GitHub Apps: ![Settings view](../../../../../../static/img/integrations/github-ocean/SelfHostedOrganizationSettings.png) 3. Click `edit` on the GitHub app created at the step before: ![GitHub integration installation page](../../../../../../static/img/integrations/github-ocean/SelfHostedEditGitHubApp.png) 4. Go to Install App -> and select the installation button on your wanted organization; 5. Choose the repositories you want the integration to be installed for: ![GitHub integration installation chooses repositories](../../../../../../static/img/integrations/github-ocean/SelfHostedInstallationRepoSelection.png) ``` -------------------------------- ### Service Dependency Configuration with Start Time Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/examples.md Example of service dependency configuration emphasizing the 'startTime' selector. This parameter specifies the look-back period in hours for fetching dependency data. ```yaml - kind: serviceDependency selector: query: 'true' environment: 'dev' startTime: 1 ``` -------------------------------- ### Install Port Agent Helm Chart Source: https://github.com/port-labs/port-docs/blob/main/docs/actions-and-automations/setup-backend/webhook/port-execution-agent/installation-methods/helm.md Installs the port-agent Helm chart into a Kubernetes cluster, creating a namespace if it doesn't exist, and configuring essential environment variables for organization ID, Kafka consumer group, and Port client credentials. ```bash helm install my-port-agent port-labs/port-agent \ --create-namespace --namespace port-agent \ --set env.normal.PORT_ORG_ID=YOUR_ORG_ID \ --set env.normal.KAFKA_CONSUMER_GROUP_ID=YOUR_KAFKA_CONSUMER_GROUP \ --set env.secret.PORT_CLIENT_ID=YOUR_PORT_CLIENT_ID \ --set env.secret.PORT_CLIENT_SECRET=YOUR_PORT_CLIENT_SECRET ``` -------------------------------- ### Port GitHub App Installation Source: https://github.com/port-labs/port-docs/blob/main/docs/guides/all/promote-to-production.md Instructions for installing Port's GitHub app to sync repositories into Port. This is a prerequisite for integrating GitHub workflows with Port. ```markdown Install Port's GitHub app by clicking [here](https://github.com/apps/getport-io/installations/new). ``` -------------------------------- ### Homepage and Markdown Widget Usage Source: https://github.com/port-labs/port-docs/blob/main/docs/guides/_implementation-guide/launch/launch.md Demonstrates how to create a detailed homepage using markdown for portal descriptions, announcements, and updates. It also shows the use of a markdown widget for similar purposes. ```markdown Add a detailed homepage to your portal with a [readme](https://docs.port.io/customize-pages-dashboards-and-plugins/dashboards/#markdown) that explains the purpose of the portal, the available self-service actions, and how to use them. Use the homepage to communicate announcements, updates, initiatives, and other important information to your users. This can also be done using a [markdown widget](https://docs.port.io/customize-pages-dashboards-and-plugins/dashboards/#markdown). ``` -------------------------------- ### Notify Users Upon Approval of Self-Service Actions Guide Source: https://github.com/port-labs/port-docs/blob/main/docs/solutions/resource-self-service/setup-approval-workflows.md This guide illustrates the capability of approval workflows by demonstrating how to notify users upon the approval of self-service actions. It is part of a series of guides showcasing Port's approval workflow features. ```markdown [Notify users upon approval of self-service actions](/guides/all/notify-users-upon-approval-of-action) ``` -------------------------------- ### Example Bitbucket Project Blueprint Source: https://github.com/port-labs/port-docs/blob/main/docs/build-your-software-catalog/sync-data-to-catalog/git/bitbucket/bitbucket-server/bitbucket-server.md An example of a Port blueprint for a Bitbucket Project, demonstrating how to map Bitbucket project data into the software catalog. ```javascript import "@port-labs/core/dist/types/blueprint" blueprint.define("bitbucket-project", { "$schema": "http://json-schema.org/draft-07/schema#", "title": "Bitbucket Project", "type": "object", "properties": { "id": { "type": "string", "description": "The unique identifier of the project." }, "key": { "type": "string", "description": "The project key." }, "name": { "type": "string", "description": "The name of the project." }, "description": { "type": "string", "description": "A description of the project." } }, "required": [ "id", "key", "name" ] }); ```