paperless-ngx/.github/workflows/ci-release.yml

name: Release
on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+-beta.rc[0-9]+'
concurrency:
  group: release-${{ github.ref }}
  cancel-in-progress: false
env:
  DEFAULT_UV_VERSION: "0.13.x"
  DEFAULT_PYTHON_VERSION: "3.12"
permissions: {}
jobs:
  wait-for-docker:
    name: Wait for Docker Build
    runs-on: ubuntu-26.04
    permissions:
      checks: read
      statuses: read
    steps:
      - name: Wait for Docker build
        uses: lewagon/wait-on-check-action@369769072fe522a3a8a85c03c96af1e5242a1994 # v1.9.1
        with:
          ref: ${{ github.sha }}
          check-name: 'Merge and Push Manifest'
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          wait-interval: 60
          checks-discovery-timeout: 1800
  build-release:
    name: Build Release
    needs: wait-for-docker
    runs-on: ubuntu-26.04
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      # ---- Frontend Build ----
      - name: Install pnpm
        uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0
        with:
          package_json_file: src-ui/package.json
      - name: Use Node.js 24
        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
        with:
          node-version: 24.x
          package-manager-cache: false
      - name: Install frontend dependencies
        run: cd src-ui && pnpm install
      - name: Build frontend
        run: cd src-ui && pnpm run build --configuration production
      # ---- Backend Setup ----
      - name: Set up Python
        id: setup-python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: false
          python-version: ${{ steps.setup-python.outputs.python-version }}
      - name: Install Python dependencies
        env:
          PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}
        run: |
          uv sync --python "${PYTHON_VERSION}" --dev --frozen
      - name: Install system dependencies
        timeout-minutes: 12
        uses: $/.github/actions/apt-install
        with:
          packages: gettext libleptonica6
      # ---- Build Documentation ----
      - name: Build documentation
        env:
          PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}
        run: |
          uv run \
            --python "${PYTHON_VERSION}" \
            --dev \
            --frozen \
            zensical build --clean
      # ---- Prepare Release ----
      - name: Generate requirements file
        run: |
          uv export --quiet --no-dev --all-extras --emit-index-url --format requirements-txt --output-file requirements.txt
      - name: Compile messages
        env:
          PAPERLESS_SECRET_KEY: "ci-release-not-a-real-secret"
          PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}
        run: |
          cd src/
          uv run \
            --python "${PYTHON_VERSION}" \
            manage.py compilemessages
      - name: Collect static files
        env:
          PAPERLESS_SECRET_KEY: "ci-release-not-a-real-secret"
          PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}
        run: |
          cd src/
          uv run \
            --python "${PYTHON_VERSION}" \
            manage.py collectstatic --no-input --clear
      - name: Assemble release package
        run: |
          mkdir -p dist/paperless-ngx/scripts

          for file_name in .dockerignore \
                          .env \
                          Dockerfile \
                          pyproject.toml \
                          uv.lock \
                          requirements.txt \
                          LICENSE \
                          README.md \
                          paperless.conf.example
          do
            cp --verbose ${file_name} dist/paperless-ngx/
          done
          mv dist/paperless-ngx/paperless.conf.example dist/paperless-ngx/paperless.conf

          cp --recursive docker/ dist/paperless-ngx/docker
          cp scripts/*.service scripts/*.sh scripts/*.socket dist/paperless-ngx/scripts/
          cp --recursive src/ dist/paperless-ngx/src
          cp --recursive site/ dist/paperless-ngx/docs
          mv static dist/paperless-ngx/

          find dist/paperless-ngx -name "__pycache__" -type d -exec rm -rf {} +
      - name: Create release archive
        run: |
          cd dist
          sudo chown -R 1000:1000 paperless-ngx/
          tar -cJf paperless-ngx.tar.xz paperless-ngx/
      - name: Upload release artifact
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: release
          path: dist/paperless-ngx.tar.xz
          retention-days: 7
  publish-release:
    name: Publish Release
    needs: build-release
    runs-on: ubuntu-26.04
    permissions:
      contents: write
      pull-requests: write
    outputs:
      prerelease: ${{ steps.get-version.outputs.prerelease }}
      changelog: ${{ steps.create-release.outputs.body }}
      version: ${{ steps.get-version.outputs.version }}
    steps:
      - name: Download release artifact
        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
        with:
          name: release
          path: ./
      - name: Get version info
        id: get-version
        env:
          REF_NAME: ${{ github.ref_name }}
        run: |
          echo "version=${REF_NAME}" >> $GITHUB_OUTPUT
          if [[ "${REF_NAME}" == *"-beta.rc"* ]]; then
            echo "prerelease=true" >> $GITHUB_OUTPUT
          else
            echo "prerelease=false" >> $GITHUB_OUTPUT
          fi
      - name: Create release and changelog
        id: create-release
        uses: release-drafter/release-drafter@978bb0b30c5ee8cdd332ced253758157150d43f0 # v7.10.0
        with:
          name: Paperless-ngx ${{ steps.get-version.outputs.version }}
          tag: ${{ steps.get-version.outputs.version }}
          version: ${{ steps.get-version.outputs.version }}
          prerelease: ${{ steps.get-version.outputs.prerelease }}
          publish: true
          commitish: ${{ steps.get-version.outputs.prerelease == 'true' && 'dev' || 'main' }}
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Upload release archive
        uses: shogo82148/actions-upload-release-asset@9ee13965a8a51926f330b424693f25fcff8f2ef6 # v1.10.6
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          upload_url: ${{ steps.create-release.outputs.upload_url }}
          asset_path: ./paperless-ngx.tar.xz
          asset_name: paperless-ngx-${{ steps.get-version.outputs.version }}.tar.xz
          asset_content_type: application/x-xz
  # ---------------------------------------------------------------------------
  # Append changelog to docs (only on non-prerelease)
  # ---------------------------------------------------------------------------
  append-changelog:
    name: Append Changelog
    needs: publish-release
    if: needs.publish-release.outputs.prerelease == 'false'
    runs-on: ubuntu-26.04
    permissions:
      contents: write
      pull-requests: write
    steps:
      - name: Checkout
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          ref: main
          persist-credentials: true # for pushing changelog branch
      - name: Set up Python
        id: setup-python
        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
        with:
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Install uv
        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
        with:
          version: ${{ env.DEFAULT_UV_VERSION }}
          enable-cache: false
          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
      - name: Update changelog
        working-directory: docs
        env:
          CHANGELOG: ${{ needs.publish-release.outputs.changelog }}
          PYTHON_VERSION: ${{ steps.setup-python.outputs.python-version }}
          VERSION: ${{ needs.publish-release.outputs.version }}
        run: |
          branch_name="${VERSION}-changelog"

          git branch "${branch_name}"
          git checkout "${branch_name}"

          printf '# Changelog\n\n%s\n' "${CHANGELOG}" > changelog-new.md

          echo "Manually linking usernames"
          sed -i -r 's|@([a-zA-Z0-9_]+) \(\[#|[@\1](https://github.com/\1) ([#|g' changelog-new.md

          echo "Removing unneeded comment tags"
          sed -i -r 's|@<!---->|@|g' changelog-new.md

          CURRENT_CHANGELOG=$(tail --lines +2 changelog.md)
          echo -e "$CURRENT_CHANGELOG" >> changelog-new.md
          mv changelog-new.md changelog.md

          uv run \
            --python "${PYTHON_VERSION}" \
            --dev \
            prek run --files changelog.md || true

          git config --global user.name "github-actions"
          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git commit -am "Changelog ${VERSION} - GHA"
          git push origin "${branch_name}"
      - name: Create pull request
        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
        env:
          VERSION: ${{ needs.publish-release.outputs.version }}
        with:
          script: |
            const { repo, owner } = context.repo;
            const version = process.env.VERSION;
            const head = `${version}-changelog`;
            const result = await github.rest.pulls.create({
              title: `Documentation: Add ${version} changelog`,
              owner,
              repo,
              head,
              base: 'main',
              body: 'This PR is auto-generated by CI.'
            });
            github.rest.issues.addLabels({
              owner,
              repo,
              issue_number: result.data.number,
              labels: ['documentation', 'skip-changelog']
            });