ArgoCD GitOps Updater Action

January 25, 2026 · View on GitHub

GitHub Action for automated Helm chart and Docker image version updates. GitOps-friendly with ArgoCD/Kustomize support, auto-discovery, semantic versioning, and notifications (Slack/Teams/Discord/Telegram)

Automatically keep your GitOps repositories up-to-date by checking for new versions of Helm charts and Docker images, creating pull requests with updates, and notifying your team.

✨ Features

🔄 Automated Version Updates - Automatically detect and update to latest semantic versions
🎯 Variant Preservation - Keeps image variants intact (alpine → alpine, slim → slim)
🔍 Auto-Discovery - Automatically find Helm charts and Docker images in your repo
📦 Multi-Registry Support - Docker Hub, ghcr.io, quay.io, gcr.io, and more
🚀 Performance Optimized - Concurrent async processing for fast version checks
🔒 Rate Limit Management - Per-registry rate limiting with authentication support
📊 Smart Notifications - Slack, Microsoft Teams, Discord, Telegram support
⚠️ Major Version Alerts - Get notified when major version updates are available
🚫 Ignore Rules - Blacklist specific images/charts or versions with regex patterns
🏷️ Semantic Versioning - Intelligent version comparison and updates
🔐 GitOps Native - Works with ArgoCD Applications and Kustomize

🚀 Quick Start

Basic Usage

name: Update Versions

on:
  schedule:
    - cron: '0 2 * * 1'  # Every Monday at 2 AM
  workflow_dispatch:

jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: drumandbytes/argocd-gitops-updater-action@v2
        with:
          config-path: '.update-config.yaml'
          create-pr: true

With Auto-Discovery

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    auto-discover: true
    create-pr: true
    pr-title: 'chore: update dependencies'

With Docker Hub Authentication

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    config-path: '.update-config.yaml'
    dockerhub-username: ${{ secrets.DOCKERHUB_USERNAME }}
    dockerhub-token: ${{ secrets.DOCKERHUB_TOKEN }}
    create-pr: true

With Notifications

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    config-path: '.update-config.yaml'
    create-pr: true
    notification-method: slack
    slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}

📋 Configuration File

You can either create .update-config.yaml manually or use auto-discovery to generate it automatically.

Manual Configuration

Create .update-config.yaml in your repository:

# Helm Charts
helmCharts:
  - name: prometheus
    repository: https://prometheus-community.github.io/helm-charts
    chartName: prometheus
    # Path to the file containing the version
    files:
      - path: apps/monitoring/prometheus/Chart.yaml
        versionKey: dependencies[0].version

  - name: grafana
    repository: https://grafana.github.io/helm-charts
    chartName: grafana
    files:
      - path: apps/monitoring/grafana/kustomization.yaml
        versionKey: helmCharts[0].version

# Docker Images
dockerImages:
  - id: postgres-primary
    repository: postgres
    registry: dockerhub
    currentTag: "16.1-alpine"
    files:
      - path: apps/database/deployment.yaml
        imageKey: spec.template.spec.containers[0].image

  - id: redis
    repository: redis
    registry: dockerhub
    currentTag: "7.2-alpine"
    files:
      - path: apps/cache/deployment.yaml
        imageKey: spec.template.spec.containers[0].image

# Ignore certain updates (optional)
ignore:
  dockerImages:
    # Ignore by ID
    - id: postgres-primary

    # Ignore by repository and tag pattern
    - repository: nginx
      tagPattern: "^.*-perl$"  # Ignore all perl variants

  helmCharts:
    # Ignore by name
    - name: legacy-chart

    # Ignore specific version patterns
    - name: prometheus
      versionPattern: "^25\\."  # Ignore version 25.x

Auto-Discovery (Recommended for Getting Started)

Don't want to create the config manually? Use auto-discovery:

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    auto-discover: true
    create-pr: true

This will:

Automatically scan your repository for:
- ArgoCD Applications with Helm charts
- Kustomize files with Helm chart references
- Kubernetes manifests with Docker images
Generate .update-config.yaml with all discovered resources
Create a PR with the generated config
Stop before running updates (you review and merge the config first)

After merging the auto-discovery PR, subsequent runs will use the config file for updates. You can run auto-discovery periodically to find new resources, or disable it and only use the existing config.

See Auto-Discovery Workflow for a complete example.

📖 Inputs

Input	Description	Required	Default
`config-path`	Path to the update configuration YAML file	No	`.update-config.yaml`
`auto-discover`	Auto-discover resources before updating	No	`false`
`working-directory`	Working directory for the action	No	`.`
`create-pr`	Create a pull request with changes	No	`true`
`pr-title`	Title for the pull request	No	`chore: update Helm charts & Docker images`
`pr-branch`	Branch name for the pull request	No	`chore/update-versions`
`pr-base`	Base branch for the pull request	No	`main`
`commit-message`	Commit message for changes	No	`chore: update Helm charts & Docker images`
`dry-run`	Run in dry-run mode without making changes	No	`false`
`python-version`	Python version to use	No	`3.14`
`notification-method`	Notification method: `telegram`, `slack`, `microsoft-teams`, `discord`, or `none`	No	`none`
`telegram-bot-token`	Telegram bot token for notifications	No	-
`telegram-chat-id`	Telegram chat ID for notifications	No	-
`slack-webhook-url`	Slack webhook URL for notifications	No	-
`teams-webhook-url`	Microsoft Teams webhook URL for notifications	No	-
`discord-webhook-url`	Discord webhook URL for notifications	No	-
`dockerhub-username`	Docker Hub username (increases rate limit 100→200 req/6h)	No	-
`dockerhub-token`	Docker Hub access token	No	-
`github-token`	GitHub token for ghcr.io authentication	No	`${{ github.token }}`

📤 Outputs

Output	Description
`discovery-changes-detected`	Whether auto-discovery found new resources (`true`/`false`)
`discovery-pr-number`	Discovery pull request number (if created)
`discovery-pr-url`	Discovery pull request URL (if created)
`changes-detected`	Whether any version update changes were detected (`true`/`false`)
`update-report`	Summary report of updates made
`pr-number`	Version update pull request number (if created)
`pr-url`	Version update pull request URL (if created)

🔧 Advanced Usage

Auto-Discovery Workflow

Automatically discover all Helm charts and Docker images in your repository:

name: Discover Resources

on:
  workflow_dispatch:

jobs:
  discover:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - uses: drumandbytes/argocd-gitops-updater-action@v2
        with:
          auto-discover: true
          create-pr: true
          pr-title: 'chore: auto-discover new resources'

This will:

Scan your repository for ArgoCD Applications, Kustomize files, and Kubernetes manifests
Extract Helm charts and Docker images
Create a PR with updated .update-config.yaml
Stop before running version updates (you review and merge first)

Dry Run Mode

Test without making changes:

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    config-path: '.update-config.yaml'
    dry-run: true

Notifications with Built-in Support

Recommended: Use the action's built-in notification support for Slack, Discord, Microsoft Teams, or Telegram:

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    config-path: '.update-config.yaml'
    create-pr: true
    # Built-in notification support - automatically sends formatted updates
    notification-method: slack
    slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}

Benefits of built-in notifications:

✅ Automatically formatted with update details
✅ Includes PR links, operation status, and update summary
✅ No additional workflow steps needed
✅ Consistent formatting across all notification platforms

Supported methods: slack, discord, microsoft-teams, telegram, or none

See Notification Examples section below for detailed setup instructions for each platform.

Using Outputs

- uses: drumandbytes/argocd-gitops-updater-action@v2
  id: updater
  with:
    config-path: '.update-config.yaml'
    create-pr: true

- name: Comment on issue
  if: steps.updater.outputs.changes-detected == 'true'
  uses: actions/github-script@v7
  with:
    script: |
      github.rest.issues.create({
        owner: context.repo.owner,
        repo: context.repo.repo,
        title: 'Version Updates Available',
        body: `${{ steps.updater.outputs.update-report }}`
      });

🔐 Authentication Setup

Docker Hub (Recommended)

Increase rate limits from 100 to 200 requests per 6 hours:

Create access token at https://hub.docker.com/settings/security
Add to repository secrets:
- DOCKERHUB_USERNAME
- DOCKERHUB_TOKEN
Use in workflow:

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    dockerhub-username: ${{ secrets.DOCKERHUB_USERNAME }}
    dockerhub-token: ${{ secrets.DOCKERHUB_TOKEN }}

GitHub Container Registry (ghcr.io)

The action automatically uses ${{ github.token }} for ghcr.io authentication. For custom tokens:

- uses: drumandbytes/argocd-gitops-updater-action@v2
  with:
    github-token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

📊 Performance & Rate Limits

Performance Features

Async Processing: Concurrent async requests for fast version checks
Smart Rate Limiting: Per-registry semaphores prevent API throttling
- Docker Hub: 3 concurrent (anonymous) / 5 concurrent (authenticated)
- GHCR: 10 concurrent
- Quay/GCR: 5 concurrent each
Helm Concurrency: 5 parallel Helm chart checks
Typical Performance: ~40-60s for 10-15 resources

Registry Rate Limits

Registry	Anonymous	Authenticated	Action Limits
Docker Hub	100 req/6h	200 req/6h	3 concurrent (anon) / 5 (auth)
ghcr.io	Limited	5,000 req/h	10 concurrent
quay.io	~100 req/min	Higher	5 concurrent
gcr.io	No strict limit	-	5 concurrent

Tip: Authenticate with Docker Hub to increase rate limits (100→200 req/6h) and concurrency (3→5).

🎯 Supported Registries

✅ Docker Hub (dockerhub, docker.io)
✅ GitHub Container Registry (ghcr.io)
✅ Quay.io (quay.io)
✅ Google Container Registry (gcr.io)
✅ Amazon ECR (public)
✅ Custom registries with standard APIs

📝 Notification Examples

The action has built-in notification support - no need to use external notification actions! Simply configure the appropriate webhook URL and notification method in the action inputs.

All notifications automatically include:

📦 Update completion status
🔌 Pull request link and number
⚙️ Operation type (created/updated)
📝 PR title
📋 Detailed update summary

Slack

Prerequisites: You need a Slack workspace. If you don't have one, create at https://slack.com/create

Create Incoming Webhook:

Go to https://api.slack.com/messaging/webhooks
Click "Create your Slack app" → "From scratch"
Name your app (e.g., "Version Updater") and select your workspace
Click "Incoming Webhooks" → Toggle "Activate Incoming Webhooks" to ON
Click "Add New Webhook to Workspace"
Select the channel where notifications will be posted → Click "Allow"
Copy the webhook URL (starts with https://hooks.slack.com/services/...)

Add to GitHub Secrets:

Repository Settings → Secrets and variables → Actions → New repository secret
Name: SLACK_WEBHOOK_URL
Value: Your webhook URL

Use in workflow:

notification-method: slack
slack-webhook-url: ${{ secrets.SLACK_WEBHOOK_URL }}

Microsoft Teams

⚠️ Note: Microsoft Teams support is implemented according to the official Microsoft Teams Incoming Webhook API documentation but has not been personally tested by the maintainer due to Teams Free tier limitations. The implementation follows the same pattern as other notification platforms (Slack, Discord, Telegram) which have been tested. If you encounter issues, please report them.

Prerequisites: You need Microsoft Teams with a team and channel (work/school account). Free tier may have limitations.

Create Incoming Webhook:

Open Microsoft Teams and go to your channel (e.g., "General")
Click "..." (three dots) next to the channel name
Select "Workflows" or "Connectors" (depends on Teams version):
- New Teams: Search for "Incoming Webhook" → Add → Configure → Copy webhook URL
- Classic Teams: Select "Incoming Webhook" → Configure → Name it → Create → Copy webhook URL

Add to GitHub Secrets:

Repository Settings → Secrets and variables → Actions → New repository secret
Name: TEAMS_WEBHOOK_URL
Value: Your webhook URL

Use in workflow:

notification-method: microsoft-teams
teams-webhook-url: ${{ secrets.TEAMS_WEBHOOK_URL }}

Discord

Prerequisites: You need a Discord server. If you don't have one, create at https://discord.com

Create Webhook:

Right-click on the channel where you want notifications → "Edit Channel"
Go to "Integrations" → "Webhooks"
Click "New Webhook" or "Create Webhook"
Give it a name (e.g., "Version Updater") and optionally upload an avatar
Click "Copy Webhook URL"
Click "Save Changes"

Add to GitHub Secrets:

Repository Settings → Secrets and variables → Actions → New repository secret
Name: DISCORD_WEBHOOK_URL
Value: Your webhook URL

Use in workflow:

notification-method: discord
discord-webhook-url: ${{ secrets.DISCORD_WEBHOOK_URL }}

Create a bot:

Open Telegram and search for @BotFather
Send /newbot and follow prompts to choose a name and username
Copy the bot token (looks like 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ)

Get your chat ID:

For personal chat: Search for @userinfobot → Send any message → Copy your chat ID
For group chat: Add your bot to a group → Add @userinfobot temporarily → Send a message → Copy the group chat ID (negative number) → Remove @userinfobot

Add to GitHub Secrets:

Repository Settings → Secrets and variables → Actions → New repository secret
Name: TELEGRAM_BOT_TOKEN (paste the bot token)
Name: TELEGRAM_CHAT_ID (paste the chat ID)

Use in workflow:

notification-method: telegram
telegram-bot-token: ${{ secrets.TELEGRAM_BOT_TOKEN }}
telegram-chat-id: ${{ secrets.TELEGRAM_CHAT_ID }}

🛠️ Troubleshooting

Rate Limit Errors (429)

Problem: Too many requests to Docker Hub

Solution:

Add Docker Hub authentication - Doubles rate limit from 100 to 200 requests per 6 hours (see Authentication Setup)
Reduce update frequency - Run weekly instead of daily (change cron schedule)

Major Version Not Updating

This is by design. The action only updates within the same major version for safety. Major version updates are reported in notifications but require manual intervention.

Auto-Discovery Not Finding Resources

Check:

Resources are in standard ArgoCD/Kustomize formats
YAML files have correct structure
Run with dry-run: true to see what's being processed

PR Creation Fails

Common causes:

No changes detected (check with dry-run: true first)
Missing permissions (add contents: write and pull-requests: write)
Branch already exists (configure pr-branch with unique name)

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for development setup, code style, and PR guidelines.

The codebase includes:

111 unit tests with pytest
ruff for linting and formatting
CI workflow for automated testing

ArgoCD GitOps Updater Action

✨ Features

🚀 Quick Start

Basic Usage

With Auto-Discovery

With Docker Hub Authentication

With Notifications

📋 Configuration File

Manual Configuration

Auto-Discovery (Recommended for Getting Started)

📖 Inputs

📤 Outputs

🔧 Advanced Usage

Auto-Discovery Workflow

Dry Run Mode

Notifications with Built-in Support

Using Outputs

🔐 Authentication Setup

Docker Hub (Recommended)

GitHub Container Registry (ghcr.io)

📊 Performance & Rate Limits

Performance Features

Registry Rate Limits

🎯 Supported Registries

📝 Notification Examples

Slack

Microsoft Teams

Discord

Telegram

🛠️ Troubleshooting

Rate Limit Errors (429)

Major Version Not Updating

Auto-Discovery Not Finding Resources

PR Creation Fails

🤝 Contributing

📄 License

🔗 Links

⭐ Show Your Support