Updatecli Deploy Action

A Forgejo Action that uses Updatecli to automatically update Helm chart versions and create pull requests for ArgoCD deployments.

Overview

This action automates the process of:

• Updating the appVersion in a Helm chart's Chart.yaml with a new application version
• Incrementing the chart's version (minor version bump)
• Creating a pull request in a Forgejo repository with the changes

Features

• 🔄 Automatic Helm chart version management
• 📈 Semantic versioning with minor version increments
• 🔀 Automated pull request creation
• 🎯 Support for different target branches (main, master, develop)
• 🏷️ Configurable Docker image tag integration
• 📝 Conventional commit-style PR titles and descriptions
• ⚙️ Custom Updatecli configuration support

Usage

name: Update Helm Chart
on:
  push:
    branches: [main, develop]

jobs:
  update-chart:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Update Helm Chart
        uses: your-org/updatecli-deploy@v1
        with:
          registry-user: ${{ vars.REGISTRY_USER }}
          registry-password: ${{ secrets.REGISTRY_PASSWORD }}
          name: my-application
          ref-name: ${{ forge.ref_name }}
          docker-tag: ${{ forge.sha }}

Inputs

Input	Description	Required	Default
updatecli-config	Path to custom Updatecli configuration file	No	${{ forge.action_path }}/updatecli.yaml
registry-url	Registry URL for the Forgejo instance	No	git.cleverthis.com
registry-user	Username for Forgejo authentication	Yes	-
registry-password	Password/token for Forgejo authentication	Yes	-
charts-repo-org	Organization/owner of the charts repository	No	infra
charts-repo-name	Name of the charts repository	No	charts
name	Name of the Helm chart/application to update	Yes	-
ref-name	Git reference name (branch) that triggered the action	Yes	-
docker-tag	Docker image tag to set as the new app version	Yes	-

Environment Variables

The action uses the following environment variables internally:

• REGISTRY_URL: Constructed from registry-url input
• REGISTRY_USER: From registry-user input
• REGISTRY_PASSWORD: From registry-password input
• CHARTS_REPO_ORG: From charts-repo-org input
• CHARTS_REPO_NAME: From charts-repo-name input
• TARGET_NAME: From name input
• NEW_APP_VERSION: From docker-tag input
• TARGET_BRANCH: Determined from ref-name input

Branch Mapping

The action maps source branches to target branches as follows:

• main or master → master
• develop → develop
• Other branches → Action will fail with an error

How It Works

1. Version Detection

• Retrieves the new application version from the docker-tag input
• Reads the current chart version from Chart.yaml

2. Version Updates

• Updates the appVersion field in Chart.yaml with the new application version
• Increments the chart version using semantic versioning (minor bump)

3. Pull Request Creation

• Creates a pull request in the specified Forgejo repository
• Uses conventional commit-style titles: chore(app-name): bump chart version and set app version to X.X.X
• Includes a detailed description with change summary

Example Scenarios

Scenario 1: Main Branch Deployment

- name: Update Production Chart
  uses: your-org/updatecli-deploy@v1
  with:
    registry-user: ${{ vars.REGISTRY_USER }}
    registry-password: ${{ secrets.REGISTRY_PASSWORD }}
    name: web-app
    ref-name: main
    docker-tag: v2.1.0

This will:

• Update web-app/Chart.yaml in the master branch
• Set appVersion to v2.1.0
• Increment the chart version (e.g., 1.2.3 → 1.3.0)

Scenario 2: Development Branch

- name: Update Development Chart
  uses: your-org/updatecli-deploy@v1
  with:
    registry-user: ${{ vars.REGISTRY_USER }}
    registry-password: ${{ secrets.REGISTRY_PASSWORD }}
    name: api-service
    ref-name: develop
    docker-tag: ${{ forge.sha }}

This will target the develop branch and use the commit SHA as the app version.

Scenario 3: Custom Configuration

- name: Update Chart with Custom Config
  uses: your-org/updatecli-deploy@v1
  with:
    updatecli-config: .forgejo/workflows/custom-updatecli.yaml
    registry-user: ${{ vars.REGISTRY_USER }}
    registry-password: ${{ secrets.REGISTRY_PASSWORD }}
    name: microservice
    ref-name: main
    docker-tag: v1.2.3

This allows you to use a custom Updatecli configuration file instead of the default one, enabling:

• Custom version increment strategies (patch, minor, major)
• Different target files or repositories
• Custom pull request templates
• Additional sources and transformations

Configuration Files

Default updatecli.yaml

By default, the action uses the built-in updatecli.yaml configuration file that defines:

• Sources: Where to get version information
• Targets: What files to update and how
• Actions: How to create pull requests
• Transformers: How to modify versions (semantic version increment)

Custom Configuration with updatecli-config

The updatecli-config input allows you to override the default configuration with your own custom Updatecli configuration file. This enables advanced customization scenarios:

When to Use Custom Configuration

• Different version increment strategies: Use patch, major, or custom increment logic instead of minor
• Multiple chart updates: Update multiple charts or files in a single run
• Custom PR templates: Use different pull request titles, descriptions, or labels
• Additional transformations: Apply custom version transformations or filters
• Different target repositories: Update charts in different repositories
• Complex workflows: Implement multi-step update processes

Example Custom Configuration

Create a custom configuration file (e.g., .forgejo/workflows/custom-updatecli.yaml):

name: Custom Helm Chart Updates

scms:
  helm-chart:
    kind: gitea
    spec:
      url: '{{ requiredEnv "REGISTRY_URL" }}'
      username: '{{ requiredEnv "REGISTRY_USER" }}'
      token: '{{ requiredEnv "REGISTRY_PASSWORD" }}'
      owner: '{{ requiredEnv "CHARTS_REPO_ORG" }}'
      repository: '{{ requiredEnv "CHARTS_REPO_NAME" }}'
      branch: '{{ requiredEnv "TARGET_BRANCH" }}'

sources:
  appVersion:
    name: Get new app version from environment
    kind: shell
    spec:
      command: echo "$NEW_APP_VERSION"
      environments:
        - name: NEW_APP_VERSION

  currentChartVersion:
    scmid: helm-chart
    name: Get current chart version
    kind: yaml
    spec:
      file: '{{ requiredEnv "TARGET_NAME" }}/Chart.yaml'
      key: $.version

targets:
  updateAppVersion:
    scmid: helm-chart
    name: Update appVersion in Chart.yaml
    kind: yaml
    sourceid: appVersion
    spec:
      file: '{{ requiredEnv "TARGET_NAME" }}/Chart.yaml'
      key: $.appVersion

  updateChartVersion:
    scmid: helm-chart
    name: Increment chart version
    kind: yaml
    sourceid: currentChartVersion
    spec:
      file: '{{ requiredEnv "TARGET_NAME" }}/Chart.yaml'
      key: $.version
    transformers:
      # Custom: Use patch increment instead of minor
      - semverinc: "patch"

actions:
  pullrequest:
    kind: gitea/pullrequest
    scmid: helm-chart
    spec:
      url: '{{ requiredEnv "SERVER_URL" }}'
      owner: '{{ requiredEnv "REPO_OWNER" }}'
      repository: '{{ requiredEnv "REPO_NAME" }}'
      username: '{{ requiredEnv "REGISTRY_USER" }}'
      token: '{{ requiredEnv "REGISTRY_PASSWORD" }}'
      # Custom PR title
      title: 'feat({{ requiredEnv "TARGET_NAME" }}): update to {{ source "appVersion" }}'
      # Custom PR body
      body: |
        ## 🚀 Automated Update

        This PR updates the **{{ requiredEnv "TARGET_NAME" }}** chart with the latest version.

        ### Changes
        - App version: `{{ source "appVersion" }}`
        - Chart version: patch increment

        ### Checklist
        - [x] Version updated automatically
        - [ ] Manual review required
        - [ ] Deploy to staging first

        ---
        *Generated by Updatecli with custom configuration*

Environment Variables Available

When using custom configurations, all the same environment variables are available:

• REGISTRY_URL: Forgejo registry URL
• REGISTRY_USER: Authentication username
• REGISTRY_PASSWORD: Authentication token
• CHARTS_REPO_ORG: Charts repository organization
• CHARTS_REPO_NAME: Charts repository name
• TARGET_NAME: Chart/application name
• NEW_APP_VERSION: New application version
• TARGET_BRANCH: Target branch (master/develop)
• SERVER_URL: Forgejo server URL (derived from REGISTRY_URL)
• REPO_OWNER: Repository owner (same as CHARTS_REPO_ORG)
• REPO_NAME: Repository name (same as CHARTS_REPO_NAME)

Chart.yaml Structure

Expected Helm chart structure:

apiVersion: v2
name: my-app
version: 1.2.3 # Will be incremented
appVersion: v1.0.0 # Will be updated with new version
description: My application Helm chart

Security Considerations

• Store Forgejo credentials in Forgejo Secrets
• Use tokens with minimal required permissions
• Ensure the registry-password has access to:
  • Read the charts repository
  • Create pull requests
  • Push to branches

Troubleshooting

Common Issues

1. Authentication Failed

   • Verify registry-user and registry-password are correct
   • Ensure the token has sufficient permissions

2. Chart Not Found

   • Check that name matches the directory name in the charts repository
   • Verify charts-repo-org and charts-repo-name are correct

3. Branch Mapping Error

   • Ensure ref-name is one of: main, master, or develop
   • Check that the target branch exists in the repository

4. Version Format Issues

   • Ensure the current chart version follows semantic versioning
   • Verify Chart.yaml has valid YAML syntax