Release Pipeline#

To make a release, a GitLab CI/CD pipeline needs to be set up in the project repository. This pipeline needs to be able to generate a release tarball and upload it to the GNOME server. The following instructions will help you set up a new release pipeline for a new GNOME project that does not have one already.

Place a .gitlab-ci.yml file containing the CI/CD pipeline configuration in the root of the project (learn more). The configuration is project-specific and should be tailored to the project’s needs, but it is highly advised to utilize a CI/CD component prepared by the GNOME Release Team.

Example of a minimal .gitlab-ci.yml file#

include:
  - component: "gitlab.gnome.org/GNOME/citemplates/release-service@master"
    inputs:
      job-stage: "release"
      dist-job-name: "build-release-tarball"              # <1.>

stages:
  - "build"
  - "release"

build-release-tarball:                                    # <2.>
  stage: "build"
  variables:
    MESON_BUILD_DIR: "_build"
  script:
    - meson setup "${MESON_BUILD_DIR}"
    - meson dist -C "${MESON_BUILD_DIR}" --include-subprojects
    - cp -r "${MESON_BUILD_DIR}/meson-dist/" "${CI_PROJECT_DIR}/public-dist/"
  artifacts:
    name: "${CI_JOB_NAME}-${CI_COMMIT_REF_NAME}"
    when: "always"
    paths:
      - "public-dist"                                     # <3.>

  1. Makes it so the release job is triggered only after the build job finishes and is successful.

  2. The job that generates the release tarball. Will differ per project. You can use a pre-existing job that creates a release tarball.

  3. Makes it so your dist tarball is exported as job artifacts. You must use “public-dist” as the name or override the tarball-artifact-path input in the component.

Steps taken by the pipeline:

  1. The pipeline defines global variables.

  2. The pipeline includes the release service component and sets the necessary inputs.

  3. The pipeline builds the project, generates the release tarball and uploads it as an artifact.

  4. The included component inner workings are triggered, which will upload the tarball to the GNOME server.

If your application is already using the Flatpak CI template, it already creates a Release Tarball for you.

Example of the `.gitlab-ci.yml for gnome-font-viewer

include:
  - project: "gnome/citemplates"
    file: "flatpak/flatpak_ci_initiative.yml"
  - component: "gitlab.gnome.org/GNOME/citemplates/release-service@master"
    inputs:
      dist-job-name: "flatpak"

flatpak:
  extends: '.flatpak'
  variables:
    MANIFEST_PATH: 'build-aux/flatpak/org.gnome.font-viewerDevel.json'
    RUNTIME_REPO: 'https://sdk.gnome.org/gnome-nightly.flatpakrepo'
    FLATPAK_MODULE: "gnome-font-viewer"
    APP_ID: 'org.gnome.font-viewerDevel'
    BUNDLE: 'org.gnome.font-viewerDevel.flatpak'

nightly:
  extends: '.publish_nightly'
  dependencies: ['flatpak']
  needs: ['flatpak']

The release process is possible only with a pipeline that has been triggered by a protected Git tag. The tag is used as a trigger to generate and name the tarball. The tarball is then uploaded to the GNOME server. This limitation lies in the security constraints of the underlying service that is used to upload the tarball.

Requirements for the GitLab project settings and pipeline invocation#

  • The project must be hosted on GNOME GitLab.

  • The project must be part of the GNOME or Incubator group.

  • The pipeline must be triggered by a tag.

  • The tag must be protected so that only maintainers can create one. This is done automatically for all projects in the GNOME group.

  • The release tarball name has to be in the format $CI_PROJECT_NAME-$CI_COMMIT_TAG.tar.xz, where $CI_PROJECT_NAME is the project name and $CI_COMMIT_TAG is the tag name (learn more).