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

Check out Port for yourself โžœย 

Create cloud resources using IaC

Implement with AI

Send this guide to your coding agent.

Prerequisite: Install Port MCP

This guide shows how to open a pull request in your Git repositoryโ€”directly from Portโ€”to create a new cloud resource using GitOps.

Prerequisitesโ€‹

  • A Port account with permissions to create self-service actions.
  • The Git Integration that is relevant for you needs to be installed.
  • A repository in your Git provider in which you can create a workflow/pipeline. We recommend naming it Port-actions.

Common use casesโ€‹

  • Platform engineers can define the logic of creating a cloud resource, including standard enforcement, security and permission boundaries.
  • Developers can easily create and track cloud resources directly from Port.

Set up data modelโ€‹

To enable tracking of cloud resource definitions in Port, we'll add a new URL property to the existing Repository blueprint. This property will point to the location of IaC templates in your Git repository, letting us seamlessly link infrastructure code to each repository.

Add a resource definitions propertyโ€‹

In this guide we will add a new property to our Repository blueprint, which we can use to access our cloud resource definitions.

  1. Go to the Data model page in Port.

  2. Find your Repository blueprint. The identifier depends on your Git provider:

    • GitHub: githubRepository.
    • GitLab: gitlabRepository.
    • Bitbucket: bitbucketRepository.
  3. Click ..., then Edit JSON.

  4. Add the property below inside schema.properties, alongside the properties that are already there.

    Resource definitions property (click to expand)
    "resource_definitions": {
    "title": "Resource definitions",
    "type": "string",
    "format": "url"
    }
  5. Click Save.

This property stays empty until the action runs. The action sets it to the URL of the repository's resources directory on the default branch. That page is available after the pull request is merged.

Set up the action's frontendโ€‹

We'll create the Create s3 bucket action by pasting its JSON definition. The definition includes the inputs and the invocation method for your Git provider.

  1. Go to the Self-service page in Port.
  2. Click + Action.
  3. Click {...} Edit JSON.
  4. Copy the JSON for your Git provider, replace the placeholders, and paste it into the editor.

The action uses the default permissions. To change them, see set self-service actions permissions.

For GitLab or Bitbucket, complete Set up the action's backend first so you have the trigger token or webhook URL.

Replace <GITHUB_ORG> and <GITHUB_REPO> with the repository that contains port-create-bucket.yml from Set up the action's backend.

Create s3 bucket action (click to expand)
{
"identifier": "create_s3_bucket",
"title": "Create s3 bucket",
"icon": "Bucket",
"description": "Create an s3 bucket",
"trigger": {
"type": "self-service",
"operation": "DAY-2",
"userInputs": {
"properties": {
"name": {
"title": "Name",
"type": "string",
"description": "Name of the bucket to create"
},
"visibility": {
"title": "Visibility",
"type": "string",
"enum": ["public", "private"],
"enumColors": {
"public": "green",
"private": "blue"
}
}
},
"required": ["name", "visibility"],
"order": ["name", "visibility"]
},
"blueprintIdentifier": "githubRepository"
},
"invocationMethod": {
"type": "GITHUB",
"org": "<GITHUB_ORG>",
"repo": "<GITHUB_REPO>",
"workflow": "port-create-bucket.yml",
"workflowInputs": {
"port_context": {
"entity": "{{ .entity.identifier }}",
"runId": "{{ .run.id }}"
},
"name": "{{ .inputs.name }}",
"visibility": "{{ .inputs.visibility }}"
},
"reportWorkflowStatus": true
}
}
  1. Click Save.

The action's frontend is now ready.

Set up the action's backendโ€‹

Now we want to write the workflow or pipeline that our action will trigger.

  1. First, let's create the necessary token and secrets. If you've already completed the scaffold a new service guide, you should already have these configured and you can skip this step.

    • Go to your Github tokens page, create a personal access token with the repo scope, and copy it (this token is needed to create a pull-request from our workflow).
    Different repositories

    Add the admin:org scope when the workflow and the Terraform files live in different repositories.

    GitHub personal access token with repo scopes
    • Open the Credentials modal and copy your Client ID and Client secret.
  2. In the repository where your workflow will reside, create 3 new secrets under Settings->Secrets and variables->Actions:

    • ORG_ADMIN_TOKEN - the personal access token you created in the previous step.

    • PORT_CLIENT_ID - the client ID you copied from your Port app.

    • PORT_CLIENT_SECRET - the client secret you copied from your Port app.

      GitHub repository secrets for Port and org token

Repository identifier and a single repo

The workflow checks out repository: <entity identifier>. That value must be owner/repo. If Ocean stored a different identifier, pass the property that is owner/repo instead. When the Terraform files and this workflow live in the same repository, skip the second checkout and open the pull request in that repository. You do not need a separate service repository or an admin:org token for that setup.

  1. Now let's create the workflow file that contains our logic. Our workflow will consist of 3 steps:

    • Creating a copy of the template file in the selected service's repository and replacing its variables with the data from the action's input.
    • Creating a pull request in the selected service's repository to add the new resource.
    • Reporting the action result back to Port, including a success or failure status, and updating the relevant service's Resource definitions property with the URL of the service's resources directory.

The URL uses the default branch, so open it after you merge the pull request.

  1. Under .github/workflows/, create a new file named port-create-bucket.yml and use the following snippet as its content:

    Github workflow (click to expand)
    name: Create cloud resource
    on:
    workflow_dispatch:
    inputs:
    port_context:
    required: true
    description: Includes the entity identifier, and the action's run id
    name:
    required: true
    description: The name of the new resource
    type: string
    visibility:
    required: true
    description: The visibility of the new resource
    type: string
    jobs:
    createResource:
    runs-on: ubuntu-latest
    outputs:
    pr_url: ${{ steps.open-pr.outputs.pull-request-url }}
    steps:
    # Checkout the workflow's repository
    - uses: actions/checkout@v6
    # Checkout the service's repository
    - uses: actions/checkout@v6
    with:
    repository: "${{ fromJson(inputs.port_context).entity }}"
    path: ./targetRepo
    token: ${{ secrets.ORG_ADMIN_TOKEN }}
    - name: Copy template file
    run: |
    mkdir -p ./targetRepo/resources
    cp templates/cloudResource.tf ./targetRepo/resources/${{ inputs.name }}.tf
    - name: Update new file data
    run: |
    sed -i 's/{{ bucket_name }}/${{ inputs.name }}/' ./targetRepo/resources/${{ inputs.name }}.tf
    sed -i 's/{{ bucket_acl }}/${{ inputs.visibility }}/' ./targetRepo/resources/${{ inputs.name }}.tf
    - name: Open a pull request
    id: open-pr
    uses: peter-evans/create-pull-request@v6
    with:
    token: ${{ secrets.ORG_ADMIN_TOKEN }}
    path: ./targetRepo
    commit-message: Create new resource - ${{ inputs.name }}
    committer: GitHub <noreply@github.com>
    author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
    signoff: false
    branch: new-resource-${{ inputs.name }}
    delete-branch: true
    title: Create new resource - ${{ inputs.name }}
    body: |
    Create new ${{ inputs.visibility }} resource - ${{ inputs.name }}
    draft: false
    create-entity-in-port-and-update-run:
    runs-on: ubuntu-latest
    needs: createResource
    steps:
    - name: UPSERT Entity
    uses: port-labs/port-github-action@v1
    with:
    identifier: ${{ fromJson(inputs.port_context).entity }}
    blueprint: githubRepository
    properties: |-
    {
    "resource_definitions": "${{ github.server_url }}/${{ fromJson(inputs.port_context).entity }}/blob/main/resources/"
    }
    clientId: ${{ secrets.PORT_CLIENT_ID }}
    clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
    baseUrl: https://api.port.io
    operation: UPSERT
    runId: ${{ fromJson(inputs.port_context).runId }}
    - name: Report success to Port
    uses: port-labs/port-github-action@v1
    with:
    clientId: ${{ secrets.PORT_CLIENT_ID }}
    clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
    baseUrl: https://api.port.io
    operation: PATCH_RUN
    runId: ${{ fromJson(inputs.port_context).runId }}
    status: "SUCCESS"
    summary: "Run completed successfully!"
    logMessage: |
    Pull request created successfully for "${{ inputs.name }}" ๐Ÿš€
    ${{ needs.createResource.outputs.pr_url }}
    link: '["${{ needs.createResource.outputs.pr_url }}"]'
    report-run-failure:
    runs-on: ubuntu-latest
    needs: [createResource, create-entity-in-port-and-update-run]
    if: ${{ always() && (needs.createResource.result == 'failure' || needs.create-entity-in-port-and-update-run.result == 'failure') }}
    steps:
    - name: Report failure to Port
    uses: port-labs/port-github-action@v1
    with:
    clientId: ${{ secrets.PORT_CLIENT_ID }}
    clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
    baseUrl: https://api.port.io
    operation: PATCH_RUN
    runId: ${{ fromJson(inputs.port_context).runId }}
    status: "FAILURE"
    summary: "Run failed"
    logMessage: "The workflow failed before it could report a successful pull request."
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:


We will now create a simple .tf file that will serve as a template for our new resource:

  • In your source repository (port-actions for example), create a file named cloudResource.tf under /templates/ (it's path should be /templates/cloudResource.tf).
  • Copy the following snippet and paste it in the file's contents:
cloudResource.tf (click to expand)
cloudResource.tf
resource "aws_s3_bucket" "example" {
provider = aws.bucket_region
name = "{{ bucket_name }}"
acl = "{{ bucket_acl }}"
}

All done! The action is ready to be executed


Let's test itโ€‹

  1. Go to the self-service hub.

  2. Find the Create s3 bucket you have created and click Execute.

  3. Select the repository, enter a bucket name, and choose public or private.

  4. Click Execute.

  5. Confirm the run succeeded and verify that the pull request was created in the selected repository.

    Successful s3 bucket action run with pull request log

To add the bucket's Terraform file to the resources directory on the default branch:

  1. Merge the pull request.

  2. Open the repository entity and click Resource definitions.

    Repository entity page with Resource definitions link

You can now create resources for your services directly from Port.

Example: S3 bucketโ€‹

Use this example when you want to create an AWS S3 bucket with Terraform and report the bucket back to Port as an entity.

This example creates:

  • An s3Bucket blueprint in Port.
  • An AWS S3 bucket.
  • An S3 bucket ACL.
  • A matching Port entity for the created bucket.

Set up the S3 bucket blueprint

Create the s3Bucket blueprint before running the Terraform example.

  1. Go to the Data model page in Port.
  2. Click + Blueprint.
  3. Click {...} Edit JSON.
  4. Copy and paste the JSON below into the editor, then click Save.
S3 bucket blueprint (click to expand)
{
"identifier": "s3Bucket",
"description": "",
"title": "S3 Bucket",
"icon": "Bucket",
"schema": {
"properties": {
"isPrivate": {
"type": "boolean",
"title": "Is private?"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}

Create the S3 bucket with Terraform

Create a main.tf file with the following Terraform definition. Replace the placeholders for access_key, secret_key, client_id, and secret before running it.

S3 bucket Terraform definition (click to expand)
terraform {
required_providers {
port = {
source = "port-labs/port-labs"
version = "~> 2.32"
}
}
}

provider "aws" {
access_key = "YOUR_ACCESS_KEY_ID"
secret_key = "YOUR_SECRET_ACCESS_KEY"
region = "eu-west-1"
}

provider "port" {
base_url = "https://api.port.io"
}

resource "aws_s3_bucket" "port-terraform-example-bucket" {
bucket = "my-port-terraform-example-bucket"
}

resource "aws_s3_bucket_acl" "port-terraform-example-bucket-acl" {
bucket = aws_s3_bucket.port-terraform-example-bucket.id
acl = "private"
}

resource "port_entity" "s3_bucket" {
depends_on = [
aws_s3_bucket.port-terraform-example-bucket
]

identifier = aws_s3_bucket.port-terraform-example-bucket.bucket
title = aws_s3_bucket.port-terraform-example-bucket.bucket
blueprint = "s3Bucket"

properties = {
string_props = {
"isPrivate" = aws_s3_bucket_acl.port-terraform-example-bucket-acl.acl == "private" ? true : false
}
}
}
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

Run the following commands to initialize Terraform, inspect the planned changes, create the infrastructure, and update Port:

terraform init
terraform plan
terraform apply

The depends_on block on the Port entity ensures Terraform creates the S3 bucket before it creates the matching s3Bucket entity in Port.

Update the S3 bucket

The isPrivate property is calculated from the bucket ACL:

properties = {
string_props = {
"isPrivate" = aws_s3_bucket_acl.port-terraform-example-bucket-acl.acl == "private" ? true : false
}
}

To change the bucket ACL, update the ACL resource:

resource "aws_s3_bucket_acl" "port-terraform-example-bucket-acl" {
bucket = aws_s3_bucket.port-terraform-example-bucket.id
acl = "public-read" # Changed from "private"
}

Run terraform apply again. Terraform updates the bucket ACL and updates the isPrivate property on the matching Port entity.

Clean up the S3 bucket example

Run terraform destroy to delete the AWS S3 bucket and the matching Port entity created in this example.

Advanced example: Developer environmentโ€‹

Use this advanced example when you want to create a complete AWS developer environment with Terraform and report it back to Port as an entity.

This example creates:

  • A developerEnvironment blueprint in Port.
  • An S3 bucket that stores generated artifacts.
  • An SQS FIFO queue that receives messages.
  • A Lambda function that is triggered by messages sent to the queue.
  • A matching Port entity for the developer environment.

Set up the developer environment blueprint

Create the developerEnvironment blueprint before running the Terraform example.

  1. Go to the Data model page in Port.
  2. Click + Blueprint.
  3. Click {...} Edit JSON.
  4. Copy and paste the JSON below into the editor, then click Save.
Developer environment blueprint (click to expand)
{
"identifier": "developerEnvironment",
"description": "",
"title": "Developer Environment",
"icon": "Environment",
"schema": {
"properties": {
"bucketUrl": {
"type": "string",
"title": "Bucket URL",
"format": "url"
},
"lambdaUrl": {
"type": "string",
"title": "Lambda URL",
"format": "url"
},
"queueUrl": {
"type": "string",
"title": "Queue URL",
"format": "url"
},
"memorySize": {
"type": "number",
"title": "Memory Size"
}
},
"required": []
},
"mirrorProperties": {},
"calculationProperties": {},
"relations": {}
}

Create the developer environment with Terraform

Download the Node.js Lambda template and save the .zip file next to your main.tf file.

Create a main.tf file with the following Terraform definition. Replace the placeholders for access_key, secret_key, client_id, and secret before running it.

Developer environment Terraform definition (click to expand)
terraform {
required_providers {
port = {
source = "port-labs/port-labs"
version = "~> 2.32"
}
}
}

provider "aws" {
access_key = "YOUR_ACCESS_KEY_ID"
secret_key = "YOUR_SECRET_ACCESS_KEY"
region = "eu-west-1"
}

provider "port" {
base_url = "https://api.port.io"
}

resource "aws_s3_bucket" "port_terraform_example_dev_env_bucket" {
bucket = "my-port-terraform-example-dev-env-bucket"
}

resource "aws_s3_bucket_acl" "port_terraform_example_dev_env_bucket-acl" {
bucket = aws_s3_bucket.port_terraform_example_dev_env_bucket.id
acl = "private"
}

resource "aws_sqs_queue" "port_terraform_example_dev_env_queue" {
name = "terraform-example-queue.fifo"
fifo_queue = true
content_based_deduplication = true
}

resource "aws_iam_role" "iam_for_lambda" {
name = "iam_for_lambda"

assume_role_policy = <<EOF
{
"Version": "2012-10-17",
"Statement": [
{
"Action": "sts:AssumeRole",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Effect": "Allow",
"Sid": ""
}
]
}
EOF
}

resource "aws_iam_role_policy_attachment" "attach_sqs_policy_for_lambda_role" {
role = aws_iam_role.iam_for_lambda.name
policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaSQSQueueExecutionRole"
}

resource "aws_lambda_function" "port_terraform_example_dev_env_lambda" {
depends_on = [
aws_sqs_queue.port_terraform_example_dev_env_queue
]

filename = "lambda_function_payload.zip"
function_name = "dev-env-function"
role = aws_iam_role.iam_for_lambda.arn
handler = "index.test"

runtime = "nodejs16.x"
}

resource "aws_lambda_function_url" "example_function_url" {
function_name = aws_lambda_function.port_terraform_example_dev_env_lambda.function_name
authorization_type = "NONE"
}

resource "aws_lambda_event_source_mapping" "event_source_mapping" {
event_source_arn = aws_sqs_queue.port_terraform_example_dev_env_queue.arn
enabled = true
function_name = aws_lambda_function.port_terraform_example_dev_env_lambda.arn
batch_size = 1
}

resource "port_entity" "dev_env" {
depends_on = [
aws_s3_bucket.port_terraform_example_dev_env_bucket,
aws_lambda_function.port_terraform_example_dev_env_lambda,
aws_sqs_queue.port_terraform_example_dev_env_queue,
aws_lambda_function_url.example_function_url
]

identifier = aws_lambda_function.port_terraform_example_dev_env_lambda.function_name
title = aws_lambda_function.port_terraform_example_dev_env_lambda.function_name
blueprint = "developerEnvironment"

properties = {
string_props = {
"bucketUrl" = "https://${aws_s3_bucket.port_terraform_example_dev_env_bucket.bucket_domain_name}"
"queueUrl" = aws_sqs_queue.port_terraform_example_dev_env_queue.id
"lambdaUrl" = aws_lambda_function_url.example_function_url.function_url
}
number_props = {
"memorySize" = aws_lambda_function.port_terraform_example_dev_env_lambda.memory_size
}
}
}
Selecting a Port API URL by account region

The port_region, port.baseUrl, portBaseUrl, port_base_url and OCEAN__PORT__BASE_URL parameters select which Port API instance to use:

Run the following commands to initialize Terraform, inspect the planned changes, create the infrastructure, and update Port:

terraform init
terraform plan
terraform apply

The depends_on block on the Port entity ensures Terraform creates the S3 bucket, Lambda function, SQS queue, and Lambda function URL before it creates the matching developerEnvironment entity in Port.

Update the developer environment

The developer environment entity maps dynamic properties directly from the AWS resources defined in Terraform. If one of those resources changes, the Port entity updates the next time you run terraform apply.

For example, increase the Lambda function memory size:

resource "aws_lambda_function" "port_terraform_example_dev_env_lambda" {
depends_on = [
aws_sqs_queue.port_terraform_example_dev_env_queue
]

filename = "lambda_function_payload.zip"
function_name = "dev-env-function"
role = aws_iam_role.iam_for_lambda.arn
handler = "index.handler"

runtime = "nodejs16.x"

memory_size = 256 # was 128
}

Run terraform apply again. Terraform updates the Lambda function and updates the memorySize property on the matching Port entity.

Clean up the developer environment example

Run terraform destroy to delete the AWS infrastructure and the matching Port entity created in this example.

Integrate daily routinesโ€‹

  • Send a Slack message to relevant people in the organization, notifying them about the new resource.
  • Send a weekly or monthly report for managers and DevOps teams showing the new resources created in this timeframe and their owners.

More relevant guidesโ€‹

An agentic SDLC platform should integrate with GitOps practices seamlessly. Developers should be able to perform routine tasks independently, without creating bottlenecks within the organization.

With Port, platform engineers can design precise and flexible self-service actions for their developers while integrating with many different backends to suit your specific needs.