Devel Freezer

Devel Freezer is a GitHub Action that can automatically notify contributors of your open-source project about the state of development. When the project is in development freeze or when the development freeze has ended.

Features

• Ability to comment on Pull Requests predefined messages based on the latest tags
• Ability to find and update comments from Devel Freezer GitHub Action
• Policy based configuration using YAML syntax
• Support for regular expressions for freezing tags definitions
• Milestones are taken into account when checking for a development freeze. If the set milestone name partially matches the tag name, then they are considered to be connected, and PR is expected to be included in a future release.

Usage

To setup Development freeze, we need three files:

• Workflow that captures Pull Request metadata (number) and uploads this data as artifact
• Workflow that runs on workflow-run trigger, downloads artifact and runs devel_freezer GitHub Action
• development-freeze configuration

Note

Setup is complicated due to GitHub permissions on GITHUB_TOKEN. When used in workflow executed from fork it has read-only permissions. By using workflow-run trigger we are able to safely overcome this limitation and it allow us to comment on Pull Requests.

name: Gather Pull Request Metadata
on:
  pull_request:
    branches: [ main ]
    types: [ opened, reopened, synchronize ]

permissions:
  contents: read

jobs:
  gather-metadata:
    runs-on: ubuntu-latest

    permissions:
      # only required for workflows in private repositories
      actions: read
      contents: read

    steps:
      - name: Repository checkout
        uses: actions/checkout@v4

      - id: Metadata
        name: Gather Pull Request Metadata
        uses: redhat-plumbers-in-action/gather-pull-request-metadata@v1

      - name: Upload Pull Request Metadata artifact
        uses: actions/upload-artifact@v4
        with:
          name: Pull Request Metadata
          path: ${{ steps.Metadata.outputs.metadata-file }}
          retention-days: 1

name: Development Freeze

on:
  workflow_run:
    workflows: [ Gather Pull Request Metadata ]
    types:
      - completed

permissions:
  contents: read

jobs:
  freezer:
    if: >
      github.event.workflow_run.event == 'pull_request' &&
      github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest

    permissions:
      # Needed for commenting on Pull Requests
      pull-requests: write

    steps:
      - id: Artifact
        name: Download Pull Request Metadata artifact
        uses: redhat-plumbers-in-action/download-artifact@v1
        with:
          name: Pull Request Metadata

      - name: Repository checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Development Freezer
        uses: redhat-plumbers-in-action/devel-freezer@v1
        with:
          pr-number: ${{ fromJSON(steps.Artifact.outputs.pr-metadata-json).number }}
          token: ${{ secrets.GITHUB_TOKEN }}

Important

fetch-depth: 0 is required in order to have access to full history including tags.

policy:
  - tags: ['alpha', 'beta']
    feedback:
      frozen-state: |
        🥶 We are currently in ...
        🙏 Please ...
      unfreeze-state: |
        😎 We are no longer in ...

  # Suport for regular expressions
  - tags: ['^(v\d*)-rc\d$']
    labels:
      allow: ['regression ⚠️']
    feedback:
      frozen-state: |
        We are currently in a development freeze phase.
        Please ...
      unfreeze-state: |
        We had successfully released a new major release.
        We are no longer in a development freeze phase.

Real-life examples

Feel free to try devel-freezer using template repository - @redhat-plumbers-in-action/development-freeze-automation

Configuration options

Action currently accepts the following options:

# ...

- uses: redhat-plumbers-in-action/devel-freezer@v1
  with:
    pr-number:    <number>
    delay:        <seconds>
    config-path:  <path to config file>
    token:        <GitHub token or PAT>

# ...

pr-number

Pull Request number.

• default value: ${{ github.event.number }}
• requirements: required

delay

Delay in seconds before the validation of the Pull Request starts. It might be useful to account for the time it takes to set labels and milestones on the Pull Request.

• default value: 0
• requirements: optional

config-path

Path to configuration file. Configuration file format is described in: Policy section.

• default value: .github/development-freeze.yml
• requirements: optional

token

GitHub token or PAT is used for creating comments on Pull Request.

# required permission
permissions:
  contents: read
  pull-requests: write

• default value: undefined
• requirements: required
• recomended value: secrets.GITHUB_TOKEN

Policy

It's required to define a freezing policy for Action to behave correctly. The policy can be defined using .github/development-freeze.yml configuration file. The structure needs to be as follows:

policy:
  - tags: ['alpha', 'beta']
    feedback:
      frozen-state: |
        🥶 We are currently in ...
        🙏 Please ...
      unfreeze-state: |
        😎 We are no longer in ...

  # Suport for regular expressions
  - tags: ['^(v\d*)-rc\d$']
    labels:
      allow: ['regression ⚠️']
    feedback:
      frozen-state: |
        We are currently in a development freeze phase.
        Please ...
      unfreeze-state: |
        We had successfully released a new major release.
        We are no longer in a development freeze phase.
  # tags: ...

tags keyword

Array of tag names and/or regular expressions describing freezing tag scheme (e.g. ^(v\d*)-rc\d$ for tags like v251-rc1, v252-rc2, etc.). Multiple freezing schemes are supported.

• requirements: required

labels.allow keyword

Array of labels that marks Pull Request as allowed to be merged during development freeze. If the label is not present, the Pull Request will be marked with freezing message when other conditions are met.

feedback.frozen-state keyword

The message that is going to be displayed in form of a comment when development freeze conditions are met. Support for a multi-line string using | YAML syntax.

• requirements: required

feedback.unfreeze-state keyword

The message that is going to replace the development freeze message when development freeze conditions are no longer met. Support for a multi-line string using | YAML syntax.

• requirements: required