Skip to content

Alfresco/alfresco-build-tools

Folders and files

NameName
Last commit message
Last commit date
Nov 7, 2023
Oct 30, 2023
Feb 6, 2020
Sep 5, 2023
Oct 13, 2022
Jun 8, 2023
Aug 3, 2023
Oct 18, 2023
Aug 3, 2023
Oct 26, 2023

Repository files navigation

alfresco-build-tools

pre-commit Codacy Badge

Build Status
GitHub CI

This repository contains shared/reusable CI configurations for GitHub Actions to serve the repositories of the Alfresco org but virtually usable by everyone.

For security-related topics of GitHub Actions, see the Security section.

Here follows the list of GitHub Actions topics available in the current document:

GitHub Actions

Java setup

Setup JDK

actions/setup-java should be used, here is a sample usage:

      - name: Set up JDK 11
        uses: actions/setup-java@v3
        with:
          java-version: '11'
          distribution: 'temurin'
          cache: 'maven'

Setup Maven Credentials

Credentials should be already available via organization secrets, otherwise they would need to be provided as repository secrets.

Since repositories hold a settings.xml file at the root with environment variables MAVEN_USERNAME and MAVEN_USERNAME filled for the username and password, only a mapping of variables is needed:

      - name: Build with Maven
        run: mvn --settings settings.xml [...]
        env:
          MAVEN_USERNAME: ${{ secrets.NEXUS_USERNAME }}
          MAVEN_USERNAME: ${{ secrets.NEXUS_PASSWORD }}

Alternatively, the s4u/maven-settings-action could be used.

Setup Maven Build Options

Maven build options can be shared for a given step on the mvn command line, or extracted as environment variables.

Sample usage:

      - name: Test with Maven
        run: mvn verify ${{ env.MAVEN_CLI_OPTS }}
        env:
          MAVEN_CLI_OPTS: --show-version -Ddocker.skip -Dlogging.root.level=off -Dspring.main.banner-mode=off

When deploying in a second step, these variables can be shared:

env:
  MAVEN_CLI_OPTS: --show-version -Dlogging.root.level=off -Dspring.main.banner-mode=off

[...]

      - name: Test with Maven
        run: mvn verify ${{ env.MAVEN_CLI_OPTS }}
      - name: Deploy with Maven
        run: mvn deploy ${{ env.MAVEN_CLI_OPTS }} -DskipTests

When migrating from Travis, depending on the previous configuration, docker.skip and docker.tag properties might need to be setup on the command line.

Here is a sample way to extract a branch name that would be used for docker images built with the build-and-push-docker-images.sh script, although using the dedicated action can also be useful.

      - name: Set stripped branch name as tag
        run: echo "STRIPPED_TAG=$(echo ${{ github.ref_name }} | sed -e 's/[^-_.[:alnum:]]/_/g')" >> $GITHUB_ENV
      - name: Docker Build and Push
        run: sh ./build-and-push-docker-images.sh
        env:
          TAG: ${{ env.STRIPPED_TAG }}

GitHub Actions provided by community

Auto cancel builds

This action is a replacement for the Travis settings Auto cancel branch builds and Auto cancel pull request builds.

Docker build and push

Consider using this official Docker action for building and pushing containers instead of doing it by hand, for buildx support, caching and more.

Docker login

Credentials should be already available via organization secrets, otherwise they would need to be provided as repository secrets.

      - name: Login to Docker Hub
        uses: docker/login-action@v2
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

      - name: Login to Quay.io
        uses: docker/login-action@v2
        with:
          registry: quay.io
          username: ${{ secrets.QUAY_USERNAME }}
          password: ${{ secrets.QUAY_PASSWORD }}

pmd

Yet Another PMD Scan is a GitHub Action primarily for Alfresco repositories. It is a bit more involved than most of the actions in this repository and so has been split out into a repository of its own.

The action runs the PMD static analysis tool to look for common programming flaws in files modified by PRs.

Retry failing step

This action retries an Action step on failure or timeout. Useful for unstable commands or that relies on remote resources that can be flaky sometimes.

SSH debug

GitHub doesn't provide any native support for SSH debug access to builds.

To debug a build is necessary to add when needed a step like the following in the workflow:

    - name: Setup tmate session
      uses: mxschmitt/action-tmate@v3
      with:
        # provide access to SSH user that triggered the build
        limit-access-to-actor: true

You can also run the step on-demand with a manually triggered build by adding the workflow_dispatch event together with a boolean input:

on:
  workflow_dispatch:
    inputs:
      debug_enabled:
        description: Enable SSH debug
        type: boolean
        required: false
        default: false

and then invoke the action step conditionally based on this event and input value:

    steps:
    - uses: actions/checkout@v3
    - name: Setup tmate session
      # run only when explicitly requested
      if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
      uses: mxschmitt/action-tmate@v3
      with:
        # provide access to SSH user that triggered the build
        limit-access-to-actor: true
      # automatically terminate after a given timeout
      timeout-minutes: 30

When executing that step, the job will block. If you want to continue with the following steps, just create a file named continue in the current workspace folder:

touch continue

Please be aware that when the last command of the job finish, also the tmate session will be terminated automatically, so you may want to add at the end of the workflow a step like:

    # wait for 5 minutes before exiting
    - run: sleep 300

Triggering a workflow in another repository

actions/github-script can be used, here is a sample:

      - name: Trigger Downstream Builds
        if: steps.is_default_branch.outputs.result == 'true'
        uses: actions/github-script@v5
        with:
          github-token: ${{ secrets.BOT_GITHUB_TOKEN }}
          script: |
            await github.rest.actions.createWorkflowDispatch({
              owner: 'Alfresco',
              repo: 'alfresco-process-connector-services',
              workflow_id: 'build.yml',
              ref: 'develop'
            });

Note that this requires using a dedicated token.

Also, the triggered workflow should allow workflow dispatch in its definition (and this configuration should be setup on the default branch):

on:
  # allows triggering workflow manually or from other jobs
  workflow_dispatch:

GitHub Actions provided by us

automate-dependabot

Handles automated approval and merge of dependabot PRs, for minor and patch version updates only:

  • automated approval on minor and patch versions
  • automated merge on patch versions

This action requires a dedicated secret (named DEPENDABOT_GITHUB_TOKEN in the sample) to setup the "auto-merge" behavior: the default GITHUB_TOKEN is not used in this case, otherwise a build would not be triggered when the PR is merged, see reference solution.

This secret should be a dependabot secret, and the token should hold the repo > repo:status and repo > public_repo scopes for public repositories. The whole list of "repo" scopes might be needed for the workflow to run ok on private repositories.

    - uses: Alfresco/alfresco-build-tools/.github/actions/automate-dependabot@ref
      with:
        token: ${{ secrets.DEPENDABOT_GITHUB_TOKEN }}

automate-propagation

Handles automated approval and merge of propagation PRs used to handle alpha releases on builds.

This action requires a dedicated secret (named BOT_GITHUB_TOKEN in the sample) to setup the "auto-merge" behavior: the default GITHUB_TOKEN is not used in this case, otherwise a build would not be triggered when the PR is merged, see reference solution.

Another token is also needed to handled approval. It can be the default GITHUB_TOKEN, but it cannot be the same one that is used for auto-merge behavior as the user might match the creator of the PR (and auto-approval of a PR is not allowed).

    - uses: Alfresco/alfresco-build-tools/.github/actions/automate-propagation@ref
      with:
        auto-merge-token: ${{ secrets.BOT_GITHUB_TOKEN }}
        approval-token: ${{ secrets.GITHUB_TOKEN }}

configure-git-author

Configures the git username and email to associate commits with the provided identity

      - uses: Alfresco/alfresco-build-tools/.github/actions/configure-git-author@ref
        with:
          username: ${{ vars.BOT_GITHUB_USERNAME }}
          email: ${{ vars.BOT_GITHUB_EMAIL }}
          global: true

The two vars in the previous snippet are workflow configuration variables that can be created at organization level and shared across different repositories.

docker-build-image

Build docker image based on supplied jar files. It replaces image-dir and image-tag in the docker file and builds it.

After the build, if grype-scan-enabled is true, it scans the image using grype and uploads the result in GitHub security.

Finally, it pushes the created image into:

  • RedHat quay.io
  • GitHub ghcr
  • AWS ECR

When using OIDC on AWS, inputs aws-access-key-id and aws-secret-access-key can be omitted: the aws-role-name input should be used instead.

      - uses: Alfresco/alfresco-build-tools/.github/actions/docker-build-image@ref
        with:
          image-tag: ${{ needs.build.outputs.version }}
          image-dir: ${{ matrix.image-dir }}
          docker-username: ${{ secrets.DOCKER_USERNAME }}
          docker-password: ${{ secrets.DOCKER_PASSWORD }}
          quay-username: ${{ secrets.QUAY_USERNAME }}
          quay-password: ${{ secrets.QUAY_PASSWORD }}
          ghcr-token: ${{ secrets.GITHUB_TOKEN }}
          aws-access-key-id: ${{ secrets.HXPS_DEV_SVC_ECR_WRITE_AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.HXPS_DEV_SVC_ECR_WRITE_AWS_SECRET_ACCESS_KEY }}
          aws-account-id: ${{ vars.ACCOUNT_ID }}
          # aws-region: ${{ vars.AWS_REGION }} # optional
          # aws-role-name: ${{ vars.AWS_ROLE_NAME }} # optional
          # grype-scan-enabled: true # optional
          # grype-fail-build: true # optional
          # preview-label: ${{ vars.PREVIEW_LABEL }} # optional

docker-dump-containers-logs

Dumps Docker containers logs. Each container's log will be stored in a separate <container_name>.log file. All files will be archived by default under containers-logs-<job_id>-<job_retry_number>-<timestamp>.tar.gz and will be available to download via the workflow's summary page. It is also possible to specify the output archive name when providing the output-archive-name parameter.

      - uses: Alfresco/alfresco-build-tools/.github/actions/docker-dump-containers-logs@ref

docker-scan-image-dirs

Scan the directories were the Dockerfiles are to feed the scanner.

      - uses: Alfresco/alfresco-build-tools/.github/actions/docker-scan-image-dirs@ref

env-load-from-yaml

To ease the migration to GitHub Actions of repositories that contains one or more yaml files containing an env.global section of Travis CI. It supports env vars referencing as value env vars defined early in the file (like Travis does).

      - uses: Alfresco/alfresco-build-tools/.github/actions/env-load-from-yaml@ref
        with:
          ignore_regex: ^BRANCH_NAME=.*
          yml_path: .travis/env.yml

free-hosted-runner-disk-space

Removes unnecessary folders and files from a GHA hosted runner. This action might be useful when we run jobs which require a lot of disk space.

      - uses: Alfresco/alfresco-build-tools/.github/actions/free-hosted-runner-disk-space@ref

By default it removes following directories:

  • /usr/share/dotnet
  • /opt/ghc
  • /usr/local/share/boost
  • $AGENT_TOOLSDIRECTORY

You can override the default behavior by specifying your own collection of files and directories using to-remove input parameter.

get-branch-name

Loads the name of the branch on which the action was called into BRANCH_NAME environment variable

      - uses: Alfresco/alfresco-build-tools/.github/actions/get-branch-name@ref

get-build-info

get-build-info loads build-related info into the runner env, in the form of generically named variables that are not necessarily specific to GitHub.

      - uses: Alfresco/alfresco-build-tools/.github/actions/get-build-info@ref

git-check-existing-tag

Checks if a tag with the given name already exists for this remote repository. Returns the output named exists with value 'true' or 'false'.

    - uses: Alfresco/alfresco-build-tools/.github/actions/git-check-existing-tag@ref
      with:
        tag: 1.0.0

get-commit-message

Loads the content of the last commit message that triggered the action into COMMIT_MESSAGE environment variable This action requires a checkout with fetch-depth option as follow:

      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - uses: Alfresco/alfresco-build-tools/.github/actions/get-commit-message@ref

git-commit-changes

Commits local changes after configuring git user and showing the status of what is going be committed. If skip-if-no-changes input is set to true then an empty commit will not be committed at all.

    - uses: Alfresco/alfresco-build-tools/.github/actions/git-commit-changes@ref
      with:
        username: ${{ secrets.BOT_GITHUB_USERNAME }}
        add-options: -u
        commit-message: "My commit message"

git-latest-tag

Gets the latest tag and commit sha for the given pattern. The result is returned in the output named tag and tag_long_sha.

      - uses: Alfresco/alfresco-build-tools/.github/actions/git-latest-tag@ref
        with:
          pattern: 1.0.0-alpha*

helm-build-chart

Run helm dep up and helm lint on the specified chart

      - uses: Alfresco/alfresco-build-tools/.github/actions/helm-build-chart@ref
        with:
          chart-dir: charts/common

helm-integration-tests

Run helm upgrade --dryn-run on the specified chart

      - name: Execute dry run
        uses: Alfresco/alfresco-build-tools/.github/actions/helm-integration-tests@ref
        with:
          chart-dir: ${{ env.CHART_DIR }}
          test-rancher-url: ${{ secrets.RANCHER2_URL }}
          test-rancher-access-key: ${{ secrets.RANCHER2_ACCESS_KEY }}
          test-rancher-secret-key: ${{ secrets.RANCHER2_SECRET_KEY }}
          test-cluster-name: ${{ env.TEST_CLUSTER_NAME }}
          test-namespace: ${{ env.TEST_NAMESPACE }}

helm-package-chart

Packages a helm chart into a .tgz file and provides the name of the file produced in the output named package-file, and its path in the output named package-file-path. The packaged file is also uploaded as an artifact and can be downloaded using actions/download-artifact.

    - uses: Alfresco/alfresco-build-tools/.github/actions/helm-package-chart@ref
      id: package-helm-chart
      with:
        chart-dir: charts/common

helm-parse-next-release

Parses the next main release version based on the content of Chart.yaml file. The result will be returned using the output named next-release. The suffix -SNAPSHOT is removed. For instance, if the version attribute in the Chart.yaml file is 1.0.0-SNAPSHOT, the result will be 1.0.0

      - uses: Alfresco/alfresco-build-tools/.github/actions/helm-parse-next-release@ref
        id: parse-next-release
        with:
          chart-dir: charts/common

helm-publish-chart

Publishes a new helm chart package (.tgz) to a helm chart repository

      - uses: Alfresco/alfresco-build-tools/.github/actions/helm-publish-chart@ref
        with:
          helm-charts-repo: Activiti/activiti-cloud-helm-charts
          helm-charts-repo-branch: gh-pages
          chart-package: ${{ steps.package-helm-chart.outputs.package-file-path }}
          token: ${{ secrets.BOT_GITHUB_TOKEN}}

helm-release-and-publish

Releases a new version of a helm chart and publishes it to a helm repository

      - uses: Alfresco/alfresco-build-tools/.github/actions/helm-release-and-publish@ref
        with:
          version: 1.0.0
          chart-dir: charts/common
          chart-repository-dir: ${{ env.COMMON_CHART_DIR }}
          helm-repository: Activiti/activiti-cloud-helm-charts
          helm-repository-branch: gh-pages
          helm-repository-token: ${{ secrets.GITHUB_TOKEN }}
          git-username:  ${{ secrets.GITHUB_USERNAME }}

helm-template-yamllint

Render Helm chart templates and pipe into yamllint, that can check for duplicated keys and other inconsistencies that helm itself doesn't care of. The action embed a yamllint configuration files that should be suitable for most use cases.

      - uses: Alfresco/alfresco-build-tools/.github/actions/helm-template-yamllint@ref
        with:
          chart-dir: helm/my-chart # defaults to current working directory
          helm-options: --values tests/values/test_values.yaml --set persistence.enabled=false # to handle mandatory values or test different rendering
          yamllint-config-path: ./.yamllint.yaml # alternative path to yamllint config to override the default one

helm-plugin

Install requested Helm plugin

     - uses: >-
         Alfresco/alfresco-build-tools/.github/actions/helm-plugin@ref
       with:
         plugin_url: https://domain/path/to/
         plugin_version: v1.0.0

plugin_version can be skipped so the latest release of the plugin will be installed

helm-update-chart-version

Updates version attribute inside Chart.yaml file:

      - uses: Alfresco/alfresco-build-tools/.github/actions/helm-update-chart-version@ref
        with:
          new-version: 1.0.0

jx-updatebot-pr

Create a Pull Request on each downstream repository using jx-updatebot.

Given .jx/updatebot.yaml spec in the alfresco-modeling-service project:

apiVersion: updatebot.jenkins-x.io/v1alpha1
kind: UpdateConfig
spec:
  rules:
    - urls:
        - https://github.com/alfresco/alfresco-process-releases
      reusePullRequest: true
      changes:
        - regex:
            pattern: "version: (.*)"
            files:
              - "docker/quay.io/alfresco/alfresco-modeling-service.yml"
        - regex:
            pattern: "<alfresco-modeling-service.version>(.*)</alfresco-modeling-service.version>"
            files:
              - pom.xml

This action will promote alpha version to alfresco-process-releases repository via pull request. It will add new commit if there is an existing PR with matching develop label.

      - name: Promote version
        uses: Alfresco/alfresco-build-tools/.github/actions/jx-updatebot-pr@ref
        with:
          version: ${{ steps.tag.outputs.version }}
          labels: develop
          pull-request-title: "promote(dep): update versions into ${{ github.ref_name }}"
          commit-title: "chore(dep): update ${{ github.repository }} version to ${{ steps.tag.outputs.version }}"
          base-branch-name: ${{ github.ref_name }}
          git-username: ${{ secrets.GIT_USERNAME }}
          git-token: ${{ secrets.GIT_TOKEN }}
          git-author-name: ${{ secrets.GIT_AUTHOR_NAME }}
          git-author-email: ${{ secrets.GIT_AUTHOR_EMAIL }}

kubectl-keep-nslogs

This action allow to collect logs from pods if they are referenced in a deployment, a statefulset or a job.

    - name: Upload pods logs
      if: always()
      uses: >-
        Alfresco/alfresco-build-tools/.github/actions/kubectl-keep-nslogs@ref
      with:
        namespace: mynsapp
        log_retention: 7

load-release-descriptor

Used to release Activiti Projects. Load release information from release.yaml file.

      - uses: Alfresco/alfresco-build-tools/.github/actions/load-release-descriptor@ref
        id: load-descriptor
        with:
          release-descriptor: release.yaml

maven-build-and-tag

Check out, builds a maven project and docker images, generating a new alpha version for it on push events:

  • publish maven artifacts to Nexus
  • push docker images to quay.io
  • create GitHub tag for the new alpha release
    outputs:
      version: ${{ steps.build-and-tag.outputs.version }}
    steps:
      - uses: Alfresco/alfresco-build-tools/.github/actions/maven-build-and-tag@ref
        id: build-and-tag
        with:
          maven-username: ${{ secrets.NEXUS_USERNAME }}
          maven-password: ${{ secrets.NEXUS_PASSWORD }}
          quay-username: ${{ secrets.QUAY_USERNAME }}
          quay-password: ${{ secrets.QUAY_PASSWORD }}
          docker-username: ${{ secrets.DOCKER_USERNAME }}
          docker-password: ${{ secrets.DOCKER_PASSWORD }}
          git-username: ${{ secrets.BOT_GITHUB_USERNAME }}

Preview option for maven-build-and-tag

There is a possibility to publish snapshot maven artifacts and docker images from an open PR. In order to use it specify preview-label input (or use default preview). Create a PR with the preview-label label. The created maven artifacts and docker images will be tagged as 0.0.1-$GITHUB_PR_NUMBER-SNAPSHOT.

maven-deploy-file

Upload one or more files to a maven server, without requiring the presence of a pom.xml. It provides a settings.xml when can find one already configured. When using a custom settings.xml, you probably want to provide also repository-id that match the credentials id to be used for deploying.

      - name: Deploy to Nexus
        uses: Alfresco/alfresco-build-tools/.github/actions/maven-deploy-file@ref
        with:
          group-id: org.alfresco
          artifact-id: custom-alfresco-distribution
          repository-url: https://nexus.alfresco.com/nexus/content/repositories/a-valid-repo/
          version: "1.2.3"
          file: output/build.jar
          classifier: binary
          files: output/build-alt.jar,output/build-alt2.jar
          classifiers: alt,alt2
          types: jar,jar
          maven-username: ${{ secrets.NEXUS_USERNAME }}
          maven-password: ${{ secrets.NEXUS_PASSWORD }}

maven-release

Used to release Activiti projects. Update versions in POM files, create git tags and publish Maven artifacts to staging repository.

      - uses: Alfresco/alfresco-build-tools/.github/actions/maven-release@ref
        with:
          repo: Activiti/Activiti
          base-ref: ${{  needs.load-release-info.outputs.activiti-tag }}
          release-version: ${{ needs.load-release-info.outputs.version }}
          staging-repository: ${{ needs.load-release-info.outputs.staging-repository }}
          git-username: ${{ secrets.GITHUB_USERNAME }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          gpg-passphrase: "${{ secrets.GPG_PASSPHRASE }}"
          gpg-secret-keys: "${{ secrets.GPG_SECRET_KEYS }}"
          gpg-owner-trust: "${{ secrets.GPG_OWNERTRUST }}"
          nexus-username: "${{ secrets.NEXUS_USERNAME }}"
          nexus-password: "${{ secrets.NEXUS_PASSWORD }}"

maven-update-pom-version

Updates pom files to the provided version

    - uses: Alfresco/alfresco-build-tools/.github/actions/maven-update-pom-version@ref
      with:
        version: 1.0.0-alpha.1

nexus-create-staging

Creates a new staging repository on Nexus, unless there is an existing repository with the same description. The resulting staging repository will be available in the output named staging-repository.

      - uses: Alfresco/alfresco-build-tools/.github/actions/nexus-create-staging@ref
        with:
          staging-description: Activiti staging ${{ steps.load-descriptor.outputs.version }}
          nexus-profile-id: "${{ secrets.NEXUS_ACTIVITI7_PROFILE_ID }}"
          nexus-username: "${{ secrets.NEXUS_USERNAME }}"
          nexus-password: "${{ secrets.NEXUS_PASSWORD }}"

nexus-close-staging

Closes the specified staging repository on Nexus.

      - uses: Alfresco/alfresco-build-tools/.github/actions/nexus-close-staging@ref
        with:
          version: ${{ inputs.version }}
          staging-repository: ${{ inputs.staging-repository}}
          nexus-username: ${{ secrets.NEXUS_USERNAME }}
          nexus-password: ${{ secrets.NEXUS_PASSWORD }}

nexus-release-staging

Releases the specified staging repository on Nexus. The repository should be in the closed status before.

      - uses: Alfresco/alfresco-build-tools/.github/actions/nexus-release-staging@ref
        with:
          version: ${{ inputs.version }}
          staging-repository: ${{ inputs.staging-repository}}
          nexus-username: ${{ secrets.NEXUS_USERNAME }}
          nexus-password: ${{ secrets.NEXUS_PASSWORD }}

pre-commit

Executes a pre-commit step.

This action is usually added in a dedicated workflow:

name: pre-commit

on:
  pull_request:
    branches: [ master ]
  push:
    branches: [ master ]

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    permissions:
      contents: write # required only when auto-commit is enabled
    steps:
      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit@ref
        with:
          auto-commit: "true" # optionally commit automated fix changes back

This action requires a pre-existing .pre-commit-config.yaml file that needs to be present into the caller repository. You can find more documentation related to pre-commit hooks in the dedicated section.

Note that this action includes an actions/checkout as a first step that usually helps when running this step as the first step in a job and is mandatory for the proper handling of auto-commit feature, unless you specify:

      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit@ref
        with:
          skip_checkout: "true"

pre-commit-default

Executes pre-commit checks using shared configuration.

The shared configuration is grouped inside different sets that can be disabled thanks to inputs (both are enabled by default):

  • check-format: handles standard formatter checks, including Java files leveraging prettier and prettier Java plugin
  • check-github-configuration: performs json schema checks on GH actions, workflows and dependabot configuration, leveraging jcheck-jsonschema

To replicate locally the same checks, the corresponding configuration files must be used:

Sample command lines:

pre-commit run -a --config /path/to/config/format-config.yaml
pre-commit run -a --config /path/to/config/github-config.yaml

Unlike the pre-commit action, the actions/checkout action is not part of this action and should explicitly be added if not already done before in the workflow:

      - uses: actions/checkout@v3
      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit-default@ref

This action can also be used in combination with the pre-commit action, that will perform a checkout anyway. This allows combining default pre-commit checks with additional local checks configured in the local .pre-commit-config.yaml file that is part of the caller repository:

      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit@ref
      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit-default@ref

Sample usage of inputs:

      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit-default@ref
        with:
          check-format: 'false'

Or:

      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit-default@ref
        with:
          check-github-configuration: 'false'

process-coverage-report

This workflow processes the coverage report to add the total coverage percentage as a comment on a PR

        id: process-coverage-report
        uses: Alfresco/alfresco-build-tools/.github/actions/process-coverage-report@ref
        with:
          paths: |
            ${{ github.workspace }}/**/build/reports/jacoco/prodNormalDebugCoverage/prodNormalDebugCoverage.xml,
            ${{ github.workspace }}/**/build/reports/jacoco/**/debugCoverage.xml
          token: ${{ secrets.GITHUB_TOKEN }}
          min-coverage-overall: 80
          min-coverage-changed-files: 90

pipenv

This workflow sets up a Python environment using the standard setup-python action and utilizes the pipenv action to manage Python dependencies declared in the Pipfile and based on the specified Python version

      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        id: setup-python
        with:
          python-version: "3.9"
      - uses: Alfresco/alfresco-build-tools/.github/actions/pipenv@ref
        with:
          python-version: ${{ steps.setup-python.outputs.python-version }}

rancher

register or detach an EKS cluster to Rancher. AWS credentials are required only when registering the cluster.

      - name: Register Cluster
        uses: Alfresco/alfresco-build-tools/.github/actions/rancher@ref
        with:
          rancher-url: ${{ env.RANCHER2_URL }}
          rancher-access-key: ${{ secrets.RANCHER2_ACCESS_KEY }}
          rancher-secret-key: ${{ secrets.RANCHER2_SECRET_KEY }}
          cluster-name: ${{ env.CLUSTER_NAME }}
          action: "register"
          aws-access-key: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: "us-east-2"

reportportal-prepare

Prepares Report Portal configuration information, and makes it available in outputs to be used by other actions.

This action is usually used in combination with reportportal-summarize.

In particular, this prepares maven command line options for Report Portal integration, building the endpoint, authentication, launch key, description. Default context information is also added (launch attributes), unless the auto-configure input is set to false.

Sample options with auto-configuration:

"-Drp.launch=short-run-push-3674979523" "-Drp.uuid=***" "-Drp.endpoint=http://localhost:8080" "-Drp.project=my-project" "-Drp.description=[Run on GitHub Actions 3674979523](https://github.com/Alfresco/alfresco-build-tools/actions/runs/3674979523)" "-Drp.attributes=branch:my-branch;event:push;repository:Alfresco/alfresco-build-tools;run:short-run-push-3674979523;myattribute:my-filter"

Sample options without auto-configuration:

"-Drp.launch=short-run-push" "-Drp.uuid=***" "-Drp.endpoint=http://localhost:8080" "-Drp.project=my-project"

Sample usage:

env:
  # the github event name and run id will be automatically added to the launch key
  RP_LAUNCH_PREFIX: my-test-run
  RP_TOKEN: ${{ secrets.RP_TOKEN }}
  # should not be a secret to be visible in summary and slack messages
  RP_URL: http://localhost:8080
  RP_PROJECT: my-project
  RP_FILTER: my-filter

[...]

    - name: Prepare Report Portal
      uses: Alfresco/alfresco-build-tools/.github/actions/reportportal-prepare@ref
      id: rp-prepare
      with:
        rp-launch-prefix: ${{ env.RP_LAUNCH_PREFIX }}
        rp-token: ${{ env.RP_TOKEN }}
        rp-url: ${{ env.RP_URL }}
        rp-project: ${{ env.RP_PROJECT }}
        rp-extra-attributes: ";myattribute:${{ env.RP_FILTER }}"

    - name: Add GitHub Step Summary
      shell: bash
      env:
        RP_ENABLED: ${{ steps.rp-prepare.outputs.enabled }}
        RP_KEY: ${{ steps.rp-prepare.outputs.key }}
        RP_URL: ${{ steps.rp-prepare.outputs.url }}
      run: |
        echo "#### ⏱ Before Tests: $(date -u +'%Y-%m-%d %H:%M:%S%:z')" >> $GITHUB_STEP_SUMMARY
        echo "#### ⚙ Configuration" >> $GITHUB_STEP_SUMMARY
        if [[ "$RP_ENABLED" == 'true' ]]; then
          echo "- [Report Portal]($RP_URL) configured with key "'`'$RP_KEY'`' >> $GITHUB_STEP_SUMMARY
        else
          echo "- Report Portal not enabled" >> $GITHUB_STEP_SUMMARY
        fi
        echo "- My filter attribute: "'`'${{ env.RP_FILTER }}'`' >> $GITHUB_STEP_SUMMARY

    - name: Run Tests (continue on error)
      id: run-tests
      shell: bash
      env:
        MAVEN_USERNAME: ${{ inputs.maven-username }}
        MAVEN_PASSWORD: ${{ inputs.maven-password }}
        RP_OPTS: ${{ steps.rp-prepare.outputs.mvn-opts }}
      run: mvn clean verify ${{ env.RP_OPTS }}
      continue-on-error: true

    - name: Update GitHub Step Summary
      shell: bash
      run: |
        echo "#### ⏱ After Tests: $(date -u +'%Y-%m-%d %H:%M:%S%:z')" >> $GITHUB_STEP_SUMMARY

    - name: Summarize Report Portal
      uses: Alfresco/alfresco-build-tools/.github/actions/reportportal-summarize@ref
      id: rp-summarize
      with:
        tests-outcome: ${{ steps.run-tests.outcome }}
        rp-launch-key: ${{ steps.rp-prepare.outputs.key }}
        rp-url: ${{ env.RP_URL }}
        rp-project: ${{ env.RP_PROJECT }}

This will create launches on Report Portal that looks like:

Report Portal Sample

This will give the following sample output on the GH Actions run summary (when used in combination with follow-up action reportportal-summarize documented in the next section):

GH Actions Summary Report Portal

reportportal-summarize

Used in combination with reportportal-prepare.

Adds a message to the steps summary when Report Portal usage is detected. Also builds a message to be sent to slack. The message contains links to the workflow Report Portal launches.

Sample usage (as follow-up of above sample):

    - name: Summarize Report Portal
      uses: Alfresco/alfresco-build-tools/.github/actions/reportportal-summarize@ref
      id: rp-summarize
      with:
        tests-outcome: ${{ steps.run-tests.outcome }}
        rp-launch-key: ${{ steps.rp-prepare.outputs.key }}
        rp-url: ${{ env.RP_URL }}
        rp-project: ${{ env.RP_PROJECT }}

    - name: Exit on failure
      if: steps.run-tests.outcome != 'success'
      shell: bash
      run: |
        echo "::error title=run-tests::Tests failed: re-throwing on error."
        exit 1

    - name: Notify Slack on failure
      if: always() && failure()
      uses: Alfresco/alfresco-build-tools/.github/actions/send-slack-notification@ref
      with:
        channel-id: "channel-id"
        token: ${{ secrets.SLACK_BOT_TOKEN }}
        message: ${{ steps.rp-summarize.outputs.slack-message }}
        append: true

This will send a slack notification that looks like:

Slack Message Report Portal

This message handles use cases where there is only one launch, multiple launches, or when no launches have been found:

Slack Message Report Portal Not Found

This will give the following sample output on the GH Actions run summary (when used in combination with the sample workflow documented in the previous section):

GH Actions Summary Report Portal

send-slack-notification-slow-job

Sends a slack notification when current run took more time than specified via max-build-time-seconds input. This action should be added at the end to correctly measure the time.

      - uses: Alfresco/alfresco-build-tools/.github/actions/send-slack-notification-slow-job@ref
        with:
          channel-id: 'channel-id'
          token: ${{ secrets.SLACK_BOT_TOKEN }}
          max-build-time-seconds: '10'

send-slack-notification

Sends a slack notification with a pre-defined payload, relying on the slackapi/slack-github-action official action.

      - uses: Alfresco/alfresco-build-tools/.github/actions/send-slack-notification@ref
        with:
          channel-id: 'channel-id'
          token: ${{ secrets.SLACK_BOT_TOKEN }}
          notification-color: '#A30200'

If not set, the default color is red.

Depending on the GitHub event, the slack message can show different kind of information (PR title, last commit message, etc...)

Sample notification on push event:

Slack Message Append

Sample notification on pull_request event:

Slack Message Append

An optional message can be given instead of the default one:

      - uses: Alfresco/alfresco-build-tools/.github/actions/send-slack-notification@ref
        with:
          channel-id: 'channel-id'
          token: ${{ secrets.SLACK_BOT_TOKEN }}
          message: "My own content"

Slack Custom Message

This message can also be appended to the default message:

      - uses: Alfresco/alfresco-build-tools/.github/actions/send-slack-notification@ref
        with:
          channel-id: "channel-id"
          token: ${{ secrets.SLACK_BOT_TOKEN }}
          message: ${{ steps.output.reportportal-summarize.outputs.message }}
          append: true

send-teams-notification

Sends a teams notification with a pre-defined payload.

      uses: Alfresco/alfresco-build-tools/.github/actions/send-teams-notification@ref
      with:
        webhook-url: ${{ secrets.MSTEAMS_WEBHOOK }}

The above webhook URL is a mandatory parameter. Make sure to Create Incoming Webhooks before using this action. Add the webhook URL as a secret at the repo level.

Sample of a SUCCESS notification on a push event.

Teams Success

Sample of a FAILURE notification on a push event.

Teams Failure

Below is the detailed description of the above message card.

  • The summary of the message card tells you the author, event name, and the repo where it was performed.

  • The below Changelog section will list the commits.

  • The build_and_test and publish are example job names passed via the needs input. If you want to display needs status, you need to explicitly send the JSON object of the needs context as an input.

        uses: Alfresco/alfresco-build-tools/.github/actions/send-teams-notification@ref
        with:
          webhook-url: ${{ secrets.MSTEAMS_WEBHOOK }}
          needs: ${{ toJson(needs) }}

    The Failure status with an image reflects the workflow status. For the ease of access, these action buttons will perform the respective actions.

    Note: You're free to configure any action items based on your workflow need. You just need to send the JSON against the overwrite input.

      {
         "@type": "OpenUri",
         "name": "Repository",
         "targets": [
           {
              "os": "default",
              "uri": "${{ github.server_url }}/${{ github.repository }}"
           }
        ]
     }

    Details of input parameter of this action:

    Input Description
    webhook-url URL of the MS Teams incoming webhook.
    needs JSON parsed needs context.
    dry-run Do not actually send the message card to the teams channel.
    raw The entire JSON object of the Message Card which will be sent to Microsoft Teams.
    overwrite JSON like object to overwrite default message.

setup-github-release-binary

setup-github-release-binary Allows the installation of a generic binary from GitHub Releases and add it to the PATH. See setup-helm-docs for a usage example.

setup-java-build

setup-java-build performs the setup of required build tools such as Java and Maven. The Maven settings file can either be placed in the repository's root folder as .ci.settings.xml, or in a different location. In the latter case, the full path to the settings file should be provided via the maven-settings input parameter. If the Maven settings file is not provided at all, then a default settings file will be installed. The default settings file requires the following environment variables to be appropriately set with valid credentials: MAVEN_USERNAME and MAVEN_PASSWORD.

      - name: Setup Java build
        uses: Alfresco/alfresco-build-tools/.github/actions/setup-java-build@ref
        with:
          java-version: "17" # optional
          java-distribution: "temurin" # optional
          maven-settings: ".ci.settings.xml" # optional

setup-kind

Spin up a local kubernetes cluster with nginx ingress exposing http/https ports.

      - name: Setup cluster
        uses: Alfresco/alfresco-build-tools/.github/actions/setup-kind@ref
        with:
          # See the available refs in the kind release notes at https://github.com/kubernetes-sigs/kind/releases
          # Make sure to use a node image built for the same KinD version
          # kind-node-image: kindest/node:v1.24.7@sha256:577c630ce8e509131eab1aea12c022190978dd2f745aac5eb1fe65c0807eb315
          ingress-nginx-ref: controller-v1.8.2
      - name: Helm deploy
        run: |
          helm dep up ./helm/chart
          helm install acs ./helm/chart

Although not required we recommend setting the `ingress-nginx-ref``to ensure repeatable builds

update-project-base-tag

Used to update a base tag in the release descriptor. It will add or update the entry release.baseTag.$PROJECT with the value specified in the input tag.

      - uses: Alfresco/alfresco-build-tools/.github/actions/update-project-base-tag@ref
        with:
          release-descriptor: release.yaml
          project: activiti
          tag: ${{ env.ALPHA_VERSION }}

validate-maven-versions

Validates Maven dependency graph versions to ensure all target includes artifacts versions align

      - uses: Alfresco/alfresco-build-tools/.github/actions/validate-maven-versions@ref
        with:
          maven-username: ${{ secrets.NEXUS_USERNAME }}
          maven-password: ${{ secrets.NEXUS_PASSWORD }}
          m2-settings-xml: settings.xml

veracode

Runs Veracode Source Clear Scan

      - uses: Alfresco/alfresco-build-tools/.github/actions/veracode@ref
        #continue-on-error: true # uncomment this line to prevent the Veracode scan step from failing the whole build
        with:
          srcclr-api-token: ${{ secrets.SRCCLR_API_TOKEN }}
          srcclr-install-options: '-DskipTestModules' # optional, additional maven options

Reusable workflows provided by us

helm-publish-new-package-version.yml

Calculates the new alpha version, creates new git tag and publishes the new package to the helm chart repository

  publish:
    uses: Alfresco/alfresco-build-tools/.github/workflows/helm-publish-new-package-version.yml@ref
    needs: build
    with:
      next-version: 7.4.0
      chart-dir: charts/common
      helm-charts-repo: Activiti/activiti-cloud-helm-charts
      helm-charts-repo-branch: gh-pages
    secrets: inherit

Cookbook

This section contains a list of recipes and common patterns organized by desired outcome.

Conditional job/step depending on PR labels

A possible approach to have a dynamic behaviour in pull_request triggered workflows, is to check the currently assigned labels. Please be aware that labels should be already applied before opening/updating a PR in order be effective.

    if: contains(github.event.pull_request.labels.*.name, 'label-name')

Serialize pull request builds

When a workflow requires access an external shared resource, or it takes a non trivial amount of time to run, it may be desirable to prevent concurrent builds of the same pr/branch by using concurrency as a top-level keyword:

name: my-workflow
on:
  pull_request:
    branches:
      - develop
  push:
    branches:
      - develop
concurrency:
  group: ${{ github.workflow }}-${{ github.head_ref || github.ref_name || github.run_id }}
  cancel-in-progress: false

The github.workflow is a reference to the workflow id, so that different workflows are part of different groups and doesn't cancel each other.

The github.head_ref is available only when workflow is triggered by pull_request event, while github.ref_name when pushing branches and tags. The github.run_id is just a fallback to not queue the workflow run when both variables are empty (when event is not related to a specific ref).

More docs on using concurrency

Known issues

realpath not available under macosx

When running pre-commit locally you may get failures with the following error:

realpath: command not found

This is because macosx lacks support for that, and it can be fixed with:

brew install coreutils

Release

Bump version defined in version.txt during a PR, release workflow is triggered automatically on PR close.

New versions should follow Semantic versioning, so:

  • A bump in the third number will be required if you are bug fixing an existing action.
  • A bump in the second number will be required if you introduced a new action or improved an existing action, ensuring backward compatibility.
  • A bump in the first number will be required if there are major changes in the repository layout, or if users are required to change their workflow config when upgrading to the new version of an existing action.