aptly-publish/README.md

CI plugin to publish Debian package on a Aptly repository

This docker image could be used as an Woodpecker CI plugin to publish one (or more) Debian package on a Aptly repository using its API. It also could be used with Gitlab CI and Forgejo Actions to define a publishing job.

This plugin will try to :

• List all changes files in the specified directory and filter on the specified source package name (if specified)
• Iter on detected changes files and foreach of then:
• the changes file is parsed to detect the source package name, the distribution and included files
• the repository name is computed (if not specified). Format: {prefix}_{distribution}_{component}. Note: if the default prefix is specified (.), it will not be used to compute the repository name.
• the current published distribution is retrieved using APTLY Publish API to:
  • check it was already manally published a first time
  • check it used a snapshot kind of sources
  • retrieve other components source snapshot
• Upload the changes file and all its included files using APTLY File Upload API in a directory named as the source package
• Include the changes file using APTLY Local Repos API
• Compute a snapshot name for the repository based on the current date and the repository name. Format: YYYYMMDD-HHMMSS_{repository name}
• Create a snapshot of the repository using APTLY Local Repos API
• Update the published distribution with this new snapshot as source of the specified component and keeping other components source snapshot.

In case of error, it will exit with a detailed error message (within the limits of what is provided by the Aptly API).

Usage

With Woodpecker CI

The below pipeline configuration demonstrates simple usage as Woodpecker CI plugin:

pipeline:
  publish:
    image: brenard/aptly-publish
    settings:
      api_url: https://your.aptly.tld/api
      api_username: myproject
      api_password:
        from_secret: aptly_api_password
      prefix: debian
      repo_component: main
      repo_name: debian_stable_main
      path: dist
      source_name: myproject
      max_retries: 2
      force_overwrite: true

Parameters:

• api_url: Your Aptly API URL (required)
• api_username: Username to authenticate on your Aptly API (required)
• api_password: Password to authenticate on your Aptly API (required)
• prefix: The publishing prefix (optional, default: .)
• repo_component: The component name to publish on (optional, default: main)
• repo_name: The repository name to publish on. If not specified, it will be computed using the specified prefix and component and the detected package distribution. See above for details.
• path: Path to the directory where files to publish are stored (optional, default: dist)
• source_name: Name of the source package to publish (optional, default: all changes files are will be publish)
• max_retries: The number of retry in case of error calling the Aptly API (optional, default: no retry)
• force_overwrite: When publishing, overwrite files in pool/ directory without notice (optional, default: false)

With Gitlab CI

The following pipeline configuration demonstrates a simple usage to build and publish a debian package:

stages:
  - build
  - publish

build:
  image: debian:11
  stage: build
  rules:
    - if: $CI_COMMIT_TAG
  script:
    - ./build.sh
  artifacts:
    paths:
      - dist/*

publish:
  image:
    name: brenard/aptly-publish:latest
    entrypoint: ["/bin/sh", "-c"]
  stage: publish
  variables:
    APTLY_API_URL: "https://your.aptly.tld/api"
    APTLY_API_USERNAME: myproject
    APTLY_PREFIX: "debian"
    APTLY_REPO_COMPONENT: "main"
    APTLY_REPO_NAME: "debian_stable_main"
    APTLY_PATH: "dist"
    APTLY_SOURCE_NAME: "myproject"
    APTLY_MAX_RETRIES: 2
    APTLY_FORCE_OVERWRITE: true
  script:
    - echo "Publish Bullseye debian packages on APT repository..."
    - aptly-publish
  needs:
    - "build"
  rules:
    - if: $CI_COMMIT_TAG

The parameters are passed using environment variables as designed with a Woodpecker CI plugin. Consequently, you could refer to the previous section for details about these parameters. For the password to request Aptly API, you have to set the APTLY_API_PASSWORD CI variable in your Gitlab project configuration (be sure to check Masked variable).

With Forgejo Actions

The following workflow configuration demonstrates a simple usage to build and publish a debian package:

---
name: Build and publish forgejo-runner Debian package
on: [create]
jobs:
  build:
    steps:
      - name: Check out repository code
        uses: actions/checkout@v4
      - name: Build Debian package
        run: ./build.sh
      - name: Upload Debian package files
        uses: actions/upload-artifact@v3
        with:
          name: dist
          path: |
            dist/*.buildinfo
            dist/*.changes
            dist/*.deb
            dist/*.dsc
            dist/*.tar.gz            

  publish:
    runs-on: docker
    container:
      image: docker.io/brenard/aptly-publish:latest
    steps:
      - name: "Download Debian package files"
        uses: actions/download-artifact@v3
        with:
          name: dist

      - name: "Publish Debian package on Aptly repository"
        uses: https://gitea.zionetrix.net/bn8/aptly-publish@master
        with:
          api_url: https://your.aptly.tld/api
          api_username: myproject
          api_password: ${{ secrets.APTLY_API_PASSWORD }}
          prefix: debian
          repo_component: main
          repo_name: debian_stable_main
          path: "./"
          source_name: myproject
          max_retries: 2
          force_overwrite: true

The parameters are passed using environment variables as designed with a Woodpecker CI plugin. Consequently, you could refer to the previous section for details about these parameters. For the password to request Aptly API, you have to set the APTLY_API_PASSWORD Actions secret in your Forgejo project configuration.