Manage Argo CD applications

Overview

In this guide, you will create Port self-service actions that execute GitHub workflows to manage Argo CD applications.

You will create two actions:

• Sync application - sync an Argo CD application from Port.
• Restart application - restart an Argo CD application's deployment and wait for it to become healthy.

Available GitHub integrations

This guide includes steps that require integration with GitHub:

• GitHub (Ocean) - uses the Ocean framework. We strongly recommend this integration for new and migrated setups.
• GitHub (Sunset) - uses a GitHub app that is in sunset and will be fully deprecated on September 15, 2026.

Prerequisites

1. Port's GitHub Ocean integration is installed.
2. Optional - Port's Argo CD integration is installed.
3. You have a GitHub repository for the workflows.

Argo CD integration

Installing Port's Argo CD integration is not required for this example, but it creates the blueprint boilerplate for you and keeps your Argo CD applications updated in Port.

Create the Argo CD application blueprint

If you do not install Port's Argo CD integration, create the following blueprint in Port.

1. Go to the Builder page of your portal.

2. Click on + Blueprint.

3. Click on {...} Edit JSON at the top right corner.

4. Add this JSON schema:

   Argo CD application blueprint (click to expand)

   {
     "identifier": "argocdApplication",
     "description": "This blueprint represents an Argo CD application",
     "title": "Running Service",
     "icon": "Argo",
     "schema": {
       "properties": {
         "gitRepo": {
           "type": "string",
           "icon": "Git",
           "title": "Repository URL",
           "description": "The URL of the Git repository containing the application source code"
         },
         "gitPath": {
           "type": "string",
           "title": "Path",
           "description": "The path within the Git repository where the application manifests are located"
         },
         "destinationServer": {
           "type": "string",
           "title": "Destination Server",
           "description": "The URL of the target cluster's Kubernetes control plane API"
         },
         "revision": {
           "type": "string",
           "title": "Revision",
           "description": "Revision contains information about the revision the comparison has been performed to"
         },
         "targetRevision": {
           "type": "string",
           "title": "Target Revision",
           "description": "Target Revision defines the revision of the source to sync the application to. In case of Git, this can be commit, tag, or branch"
         },
         "syncStatus": {
           "type": "string",
           "title": "Sync Status",
           "enum": [
             "Synced",
             "OutOfSync",
             "Unknown"
           ],
           "enumColors": {
             "Synced": "green",
             "OutOfSync": "red",
             "Unknown": "lightGray"
           },
           "description": "Status is the sync state of the comparison"
         },
         "healthStatus": {
           "type": "string",
           "title": "Health Status",
           "enum": [
             "Healthy",
             "Missing",
             "Suspended",
             "Degraded",
             "Progressing",
             "Unknown"
           ],
           "enumColors": {
             "Healthy": "green",
             "Missing": "yellow",
             "Suspended": "purple",
             "Degraded": "red",
             "Progressing": "blue",
             "Unknown": "lightGray"
           },
           "description": "Status holds the status code of the application or resource"
         },
         "createdAt": {
           "title": "Created At",
           "type": "string",
           "format": "date-time",
           "description": "The created timestamp of the application"
         },
         "labels": {
           "type": "object",
           "title": "Labels",
           "description": "Map of string keys and values that can be used to organize and categorize object"
         },
         "annotations": {
           "type": "object",
           "title": "Annotations",
           "description": "Annotations are unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata"
         }
       },
       "required": []
     },
     "mirrorProperties": {},
     "calculationProperties": {},
     "relations": {
       "project": {
         "title": "Argo CD Project",
         "target": "argocdProject",
         "required": false,
         "many": false
       },
       "cluster": {
         "title": "Argo CD Cluster",
         "target": "argocdCluster",
         "required": false,
         "many": false
       },
       "namespace": {
         "title": "Argo CD Namespace",
         "target": "argocdNamespace",
         "required": false,
         "many": false
       }
     }
   }

5. Click Save to create the blueprint.

Synchronize Argo CD application

Use this action when you want developers to sync an Argo CD application from Port without opening Argo CD directly.

Add GitHub secrets for sync

In your GitHub repository, go to Settings > Secrets and add the following secrets:

• ARGOCD_TOKEN - your Argo CD token. See the Argo CD API docs.
• ARGOCD_APPLICATION_HOST - the host URL of your deployed Argo CD instance. For example, my-argocd-app.com.
• PORT_CLIENT_ID - your Port client ID. See find your Port credentials.
• PORT_CLIENT_SECRET - your Port client secret. See find your Port credentials.

Create the sync workflow

Create a workflow file under .github/workflows/sync-argocd-app.yaml with the following content:

Dedicated Workflows Repository

We recommend creating a dedicated repository for the workflows that are used by Port actions.

Sync workflow (click to expand)

sync-argocd-app.yaml

name: Sync Argo CD application

on:
  workflow_dispatch:
    inputs:
      application_name:
        description: The Argo CD application name. For example, app.example.com.
        required: true
      port_context:
        required: true
        description: Includes blueprint, run ID, and entity identifier from Port.

jobs:
  sync-argocd-app:
    runs-on: ubuntu-latest
    steps:
      - name: Log sync request
        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).run_id }}
          logMessage: "About to make a request to the Argo CD server."

      - name: Sync Argo CD application
        uses: omegion/argocd-actions@v1
        with:
          address: ${{ secrets.ARGOCD_APPLICATION_HOST }}
          token: ${{ secrets.ARGOCD_TOKEN }}
          action: sync
          appName: ${{ github.event.inputs.application_name }}

      - name: Log if sync request fails
        if: failure()
        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).run_id }}
          logMessage: "Request to sync Argo CD application failed."

      - name: Report sync success
        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).run_id }}
          logMessage: "Successfully synced Argo CD application."

Add the sync action in Port

Create a self-service action using the following JSON configuration.

GitHub (Ocean)

Sync Argo CD application (click to expand)

Replace the variables

• <YOUR_GITHUB_OCEAN_INTEGRATION_ID> - your GitHub Ocean integration installation ID.
• <GITHUB_ORG> - your GitHub organization or user name.
• <GITHUB_REPO> - your GitHub repository name.

{
  "identifier": "argocdApplication_sync_application",
  "title": "Sync Application",
  "icon": "Argo",
  "description": "Sync an Argo CD application",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "application_name": {
          "title": "Application Name",
          "description": "Argo CD application name",
          "icon": "Argo",
          "type": "string",
          "default": {
            "jqQuery": ".entity.title"
          }
        }
      },
      "required": [
        "application_name"
      ],
      "order": [
        "application_name"
      ]
    },
    "blueprintIdentifier": "argocdApplication"
  },
  "invocationMethod": {
    "type": "INTEGRATION_ACTION",
    "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
    "integrationActionType": "dispatch_workflow",
    "integrationActionExecutionProperties": {
      "org": "<GITHUB_ORG>",
      "repo": "<GITHUB_REPO>",
      "workflow": "sync-argocd-app.yaml",
      "workflowInputs": {
        "application_name": "{{.inputs.\"application_name\"}}",
        "port_context": {
          "entity": "{{.entity.identifier}}",
          "blueprint": "{{.action.blueprint}}",
          "run_id": "{{.run.id}}"
        }
      },
      "reportWorkflowStatus": true
    }
  },
  "requiredApproval": false
}

GitHub (Sunset)

Sync Argo CD application (click to expand)

Modification Required

Make sure to replace <GITHUB_ORG> and <GITHUB_REPO> with your GitHub organization and repository names respectively.

{
  "identifier": "argocdApplication_sync_application",
  "title": "Sync Application",
  "icon": "Argo",
  "description": "Sync an Argo CD application",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "application_name": {
          "title": "Application Name",
          "description": "Argo CD application name",
          "icon": "Argo",
          "type": "string",
          "default": {
            "jqQuery": ".entity.title"
          }
        }
      },
      "required": [
        "application_name"
      ],
      "order": [
        "application_name"
      ]
    },
    "blueprintIdentifier": "argocdApplication"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "<GITHUB_ORG>",
    "repo": "<GITHUB_REPO>",
    "workflow": "sync-argocd-app.yaml",
    "workflowInputs": {
      "application_name": "{{.inputs.\"application_name\"}}",
      "port_context": {
        "entity": "{{.entity.identifier}}",
        "blueprint": "{{.action.blueprint}}",
        "run_id": "{{.run.id}}"
      }
    },
    "reportWorkflowStatus": true
  },
  "requiredApproval": false
}

Test the sync action

1. Go to the Self-service hub.

2. Click Execute on the Sync Application action.

3. Choose the Argo CD application you want to sync.

4. If the Application Name field does not auto-fill, enter the application name manually.

5. Click Execute.

6. Wait for the application to synchronize in Argo CD.

Restart Argo CD application

Use this action when you want developers to restart an Argo CD application's deployment from Port and wait for the application to become healthy.

Add GitHub secrets for restart

In your GitHub repository, go to Settings > Secrets and add the following secrets:

• ARGO_CD_PASSWORD - your Argo CD password.
• ARGO_CD_USERNAME - your Argo CD username.
• ARGOCD_SERVER - the host URL or server of your deployed Argo CD instance without http or https. For example, my-argocd-app.com.
• PORT_CLIENT_ID - your Port client ID. See get API token.
• PORT_CLIENT_SECRET - your Port client secret. See get API token.

Create the restart workflow

Create a workflow file under .github/workflows/restart-argocd-app.yaml with the following content:

Dedicated Workflows Repository

We recommend creating a dedicated repository for the workflows that are used by Port actions.

Restart workflow (click to expand)

restart-argocd-app.yaml

name: Restart deployment in Argo CD

on:
  workflow_dispatch:
    inputs:
      application_name:
        description: Argo CD application name.
        required: true
      insecure:
        description: Use insecure connection. true or false.
        required: false
        default: "false"
      port_context:
        required: true
        description: Includes blueprint, run ID, and entity identifier from Port.

jobs:
  restart-deployment:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Install Argo CD CLI
        run: |
          curl -sSL -o /usr/local/bin/argocd https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
          chmod +x /usr/local/bin/argocd

      - name: Report failed Argo CD CLI installation
        if: failure()
        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).run_id }}
          logMessage: "Failed to install Argo CD CLI."

      - name: Report successful Argo CD CLI installation
        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).run_id }}
          logMessage: "Successfully installed Argo CD CLI."

      - name: Set insecure flag
        run: |
          echo "INSECURE_FLAG=" >> $GITHUB_ENV
          if [ "${{ inputs.insecure }}" == "true" ]; then
            echo "INSECURE_FLAG=--insecure" >> $GITHUB_ENV
          fi

      - name: Log in to Argo CD
        run: |
          argocd login ${{ secrets.ARGOCD_SERVER }} --username ${{ secrets.ARGO_CD_USERNAME }} --password ${{ secrets.ARGO_CD_PASSWORD }} $INSECURE_FLAG

      - name: Report failed Argo CD login
        if: failure()
        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).run_id }}
          logMessage: "Failed to log in to Argo CD. Check your credentials."

      - name: Report successful Argo CD login
        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).run_id }}
          logMessage: "Successfully logged in to Argo CD through the CLI."

      - name: Restart Argo CD deployment
        run: |
          argocd app actions run ${{ inputs.application_name }} restart --kind Deployment

      - name: Report failed restart
        if: failure()
        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).run_id }}
          logMessage: "Failed to restart Argo CD deployment."

      - name: Report wait for application stability
        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).run_id }}
          logMessage: "Successfully restarted deployment. Waiting for the application to stabilize."

      - name: Wait for application stability
        run: |
          argocd app wait ${{ inputs.application_name }} --sync
          argocd app wait ${{ inputs.application_name }} --health
        timeout-minutes: 60

      - name: Report healthy state
        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).run_id }}
          logMessage: "Application reached a synchronized and healthy state."

      - name: Report application instability
        if: failure()
        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).run_id }}
          logMessage: "Application failed to stabilize."

      - name: Fetch application details
        run: |
          argocd app get ${{ inputs.application_name }} --output json > app_details.json
          echo "response<<EOF" >> $GITHUB_ENV
          cat app_details.json >> $GITHUB_ENV
          echo "EOF" >> $GITHUB_ENV

      - name: Log before upserting entity
        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).run_id }}
          logMessage: "Reporting the restarted application back to Port."

      - name: Process title
        run: |
          PROCESSED_TITLE=$(echo '${{ env.response }}' | jq -r '.metadata.name' | sed 's/[^a-zA-Z0-9-]//g' | awk 'BEGIN{OFS=FS="-"} {for(i=1; i<=NF; i++) $i=toupper(substr($i,1,1)) tolower(substr($i,2)) }1')
          echo "PROCESSED_TITLE=$PROCESSED_TITLE" >> $GITHUB_ENV
        shell: bash

      - name: Upsert entity
        uses: port-labs/port-github-action@v1
        with:
          identifier: ${{ fromJson(env.response).metadata.name }}
          title: "${{ env.PROCESSED_TITLE }}"
          blueprint: ${{ fromJson(inputs.port_context).blueprint }}
          properties: |
            {
              "namespace": "${{ fromJson(env.response).metadata.namespace }}",
              "gitRepo": "${{ fromJson(env.response).spec.source.repoURL }}",
              "gitPath": "${{ fromJson(env.response).spec.source.path }}",
              "destinationServer": "${{ fromJson(env.response).spec.destination.server }}",
              "syncStatus": "${{ fromJson(env.response).status.sync.status }}",
              "healthStatus": "${{ fromJson(env.response).status.health.status }}",
              "createdAt": "${{ fromJson(env.response).metadata.creationTimestamp }}"
            }
          relations: "${{ toJson(fromJson(inputs.port_context).relations) }}"
          clientId: ${{ secrets.PORT_CLIENT_ID }}
          clientSecret: ${{ secrets.PORT_CLIENT_SECRET }}
          baseUrl: https://api.port.io
          operation: UPSERT
          runId: ${{ fromJson(inputs.port_context).run_id }}

      - name: Log if upserting entity fails
        if: failure()
        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).run_id }}
          logMessage: "Failed to upsert restarted Argo CD application entity to Port."

      - name: Log after upserting entity
        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).run_id }}
          logMessage: "Entity upsert was successful."

Add the restart action in Port

Create a self-service action using the following JSON configuration.

GitHub (Ocean)

Restart Argo CD application (click to expand)

Replace the variables

• <YOUR_GITHUB_OCEAN_INTEGRATION_ID> - your GitHub Ocean integration installation ID.
• <GITHUB_ORG> - your GitHub organization or user name.
• <GITHUB_REPO> - your GitHub repository name.

{
  "identifier": "argocdApplication_restart_application",
  "title": "Restart Application",
  "icon": "Argo",
  "description": "Restart an Argo CD application",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "application_name": {
          "title": "Application Name",
          "description": "Argo CD application name",
          "icon": "Argo",
          "type": "string",
          "default": {
            "jqQuery": ".entity.title"
          }
        },
        "insecure": {
          "title": "Insecure",
          "description": "Use insecure connection",
          "icon": "Argo",
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "application_name"
      ],
      "order": [
        "application_name",
        "insecure"
      ]
    },
    "blueprintIdentifier": "argocdApplication"
  },
  "invocationMethod": {
    "type": "INTEGRATION_ACTION",
    "installationId": "<YOUR_GITHUB_OCEAN_INTEGRATION_ID>",
    "integrationActionType": "dispatch_workflow",
    "integrationActionExecutionProperties": {
      "org": "<GITHUB_ORG>",
      "repo": "<GITHUB_REPO>",
      "workflow": "restart-argocd-app.yaml",
      "workflowInputs": {
        "application_name": "{{.inputs.\"application_name\"}}",
        "insecure": "{{.inputs.\"insecure\"}}",
        "port_context": {
          "entity": "{{.entity.identifier}}",
          "blueprint": "{{.action.blueprint}}",
          "run_id": "{{.run.id}}",
          "relations": "{{.entity.relations}}"
        }
      },
      "reportWorkflowStatus": true
    }
  },
  "requiredApproval": false
}

GitHub (Sunset)

Restart Argo CD application (click to expand)

Modification Required

Make sure to replace <GITHUB_ORG> and <GITHUB_REPO> with your GitHub organization and repository names respectively.

{
  "identifier": "argocdApplication_restart_application",
  "title": "Restart Application",
  "icon": "Argo",
  "description": "Restart an Argo CD application",
  "trigger": {
    "type": "self-service",
    "operation": "DAY-2",
    "userInputs": {
      "properties": {
        "application_name": {
          "title": "Application Name",
          "description": "Argo CD application name",
          "icon": "Argo",
          "type": "string",
          "default": {
            "jqQuery": ".entity.title"
          }
        },
        "insecure": {
          "title": "Insecure",
          "description": "Use insecure connection",
          "icon": "Argo",
          "type": "boolean",
          "default": false
        }
      },
      "required": [
        "application_name"
      ],
      "order": [
        "application_name",
        "insecure"
      ]
    },
    "blueprintIdentifier": "argocdApplication"
  },
  "invocationMethod": {
    "type": "GITHUB",
    "org": "<GITHUB_ORG>",
    "repo": "<GITHUB_REPO>",
    "workflow": "restart-argocd-app.yaml",
    "workflowInputs": {
      "application_name": "{{.inputs.\"application_name\"}}",
      "insecure": "{{.inputs.\"insecure\"}}",
      "port_context": {
        "entity": "{{.entity.identifier}}",
        "blueprint": "{{.action.blueprint}}",
        "run_id": "{{.run.id}}",
        "relations": "{{.entity.relations}}"
      }
    },
    "reportWorkflowStatus": true
  },
  "requiredApproval": false
}

Test the restart action

1. Go to the Self-service hub.

2. Click Execute on the Restart Application action.

3. Choose the Argo CD application you want to restart.

4. If the Application Name field does not auto-fill, enter the application name manually.

5. Click Execute.

6. Wait for the application to restart and report a healthy state.

More Argo CD actions

• Rollback Argo CD deployment using Port self-service actions.