deployer

OpenShift Deployer

Deploy to OpenShift using templates. This action is a wrapper around the OpenShift CLI (oc) and is intended to be used with OpenShift 4.x.

Testing has only been done with public images (ghcr.io, hub.docker.com) so far.

Usage

- uses: bcgov/actions-openshift/deployer@vX.Y.Z
  with:
    ### Required

    # OpenShift template file
    file: frontend/openshift.deploy.yml

    # OpenShift project/namespace
    oc_namespace: abc123-dev

    # OpenShift server
    oc_server: https://api.silver.devops.gov.bc.ca:6443
    
    # OpenShift token
    # Usually available as a secret in your project/namespace
    oc_token: ${{ secrets.OC_TOKEN }}


    ### Typical / recommended
    
    # Overwrite objects using `oc apply` (true) or create once with `oc create` (false)
    # With overwrite: false, AlreadyExists is tolerated while other errors fail
    overwrite: "true"

    # Template parameters/variables to pass
    parameters: -p ZONE=${{ github.event.number }}

    # Timeout seconds, only affects the OpenShift deployment (apply/create)
    # Default = "15m"
    timeout: "15m"

    # Paths to diff for build triggering (one path per line); omit to always build
    # Optional, defaults to nothing, which forces a build
    triggers: |
      frontend/


    ### Usually a bad idea / not recommended

    # Overrides the default branch to diff against
    # Defaults to the default branch, usually `main`
    ref: ${{ github.event.repository.default_branch }}

    # Override default OpenShift CLI (oc) version; e.g. 4.13

    # Repository to clone and process
    # Useful for consuming other repos, defaults to the current one
    repository: ${{ github.repository }}

Example, Single Template

Deploy a single template. Multiple GitHub secrets are used.

deploys:
  name: Deploys
  runs-on: ubuntu-24.04
  steps:
    - name: Deploys
      uses: bcgov/actions-openshift/deployer@vX.Y.Z
      with:
        file: frontend/openshift.deploy.yml
        oc_namespace: ${{ vars.OC_NAMESPACE }}
        oc_server: ${{ vars.OC_SERVER }}
        oc_token: ${{ secrets.OC_TOKEN }}
        overwrite: true
        parameters:
          -p MIN_REPLICAS=1 -p MAX_REPLICAS=2
          -p PR_NUMBER=${{ github.event.number }}
        triggers: |
          frontend/

Example, Matrix / Multiple Templates

Deploy multiple templates in parallel. Runs on pull requests (PRs).

deploys:
name: Deploys
runs-on: ubuntu-24.04
  strategy:
    matrix:
    name: [backend, database, frontend, init]
    include:
      - name: backend
        file: backend/openshift.deploy.yml
        overwrite: true
        parameters: -p MIN_REPLICAS=1 -p MAX_REPLICAS=2
        triggers: |
          backend/
      - name: database
        overwrite: false
        file: database/openshift.deploy.yml
      - name: frontend
        overwrite: true
        file: frontend/openshift.deploy.yml
        parameters: -p MIN_REPLICAS=1 -p MAX_REPLICAS=2
        triggers: |
          backend/
          frontend/
      - name: init
        overwrite: false
        file: common/openshift.init.yml
steps:
  - name: Deploys
    uses: bcgov/actions-openshift/deployer@vX.Y.Z
    with:
      name: ${{ matrix.name }}
      file: ${{ matrix.file }}
      oc_namespace: ${{ vars.OC_NAMESPACE }}
      oc_server: ${{ vars.OC_SERVER }}
      oc_token: ${{ secrets.OC_TOKEN }}
      overwrite: ${{ matrix.overwrite }}
      parameters:
        -p COMMON_TEMPLATE_VAR=whatever-${{ github.event.number }}
        ${{ matrix.parameters }}
      triggers: ${{ matrix.triggers }}

Example, Matrix

Deploy an OpenShift template. When values (e.g. overwrite, triggers) are not provided defaults will be used. This is convenient, but unintuitive.

deploys:
name: Deploys
runs-on: ubuntu-24.04
  strategy:
    matrix:
    name: [database, frontend]
    include:
      - name: database
        overwrite: false
        file: database/openshift.deploy.yml
      - name: frontend
        file: frontend/openshift.deploy.yml
        parameters: -p MIN_REPLICAS=1 -p MAX_REPLICAS=2
        triggers: |
          backend/
          frontend/
steps:
  - name: Deploys
    uses: bcgov/actions-openshift/deployer@vX.Y.Z
    with:
      name: ${{ matrix.name }}
      file: ${{ matrix.file }}
      oc_namespace: ${{ vars.OC_NAMESPACE }}
      oc_server: ${{ vars.OC_SERVER }}
      oc_token: ${{ secrets.OC_TOKEN }}
      overwrite: ${{ matrix.overwrite }}
      parameters: ${{ matrix.parameters }}
      triggers: ${{ matrix.triggers }}

Example, Using a different endpoint for deployment check

Deploy a template and set the after deployment check to hit the /health endpoint. Multiple GitHub secrets are used.

deploys:
  name: Deploys
  runs-on: ubuntu-24.04
  steps:
    - name: Deploys
      uses: bcgov/actions-openshift/deployer@vX.Y.Z
      with:
        file: backend/openshift.deploy.yml
        oc_namespace: ${{ vars.OC_NAMESPACE }}
        oc_server: ${{ vars.OC_SERVER }}
        oc_token: ${{ secrets.OC_TOKEN }}
        overwrite: true
        parameters:
          -p MIN_REPLICAS=1 -p MAX_REPLICAS=2
          -p PR_NUMBER=${{ github.event.number }}
        triggers: ${{ matrix.triggers }}

Lite Mode for Pull Requests

Pull request (PR) deployments will automatically use lite mode. This is ideal for resource-limited environments.

Object types removed:

• HorizontalPodAutoscaler
• PodDisruptionBudget

Deployment modifications:

• Replicas limited to 1 (deployment.spec.replicas)
• Rollout strategy limited to Recreate (deployment.spec.strategy.type)

Output

The action will return a boolean (true|false) of whether a deployment has been triggered. It can be useful for follow-up tasks, like running tests.

- id: meaningful_id_name
  uses: bcgov/actions-openshift/deployer@vX.Y.Z
  ...

- needs: [id]
  run: |
    echo "Triggered = ${{ steps.meaningful_id_name.outputs.triggered }}"

Unsupported Inputs

The inputs delete_completed and post_rollout are not supported. Use the sibling oc-runner action for that work.

The inputs verification_path, verification_retry_attempts and verification_retry_seconds are not supported. Use OpenShift health checks instead.

Troubleshooting

Dependabot Pull Requests Failing

Pull requests created by Dependabot require their own secrets. See GitHub Repo > Settings > Secrets > Dependabot.

Re-deploy didn't roll out

When a template is deployed again with the same image tag (e.g. the PR number), the rendered Deployment is identical to what's already running, so oc apply changes nothing and the pods keep the old image.

Teams deploying by a reused tag should add a RANDOM_EXPRESSION parameter and use it as a pod environment variable. It's regenerated on every deployment, so each deploy rolls out.

parameters:
  - name: RANDOM_EXPRESSION
    description: Random expression to make sure deployments update
    from: "[a-zA-Z0-9]{32}"
    generate: expression
objects:
  - kind: Deployment
    ...
    spec:
      template:
        spec:
          containers:
            - name: ${NAME}
              env:
                - name: RANDOM_EXPRESSION
                  value: ${RANDOM_EXPRESSION}

Leave it off database templates, or the database restarts on every deployment.

Deploying by commit SHA tag avoids the need for it, since every push changes the image reference. quickstart-openshift does this for pull requests, and it's becoming the default.

Feedback

Please contribute your ideas! Issues and pull requests are appreciated.