alfresco-build-tools

Build	Status
Travis CI
GitHub

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

Travis should be considered in maintenance mode only since we are actively migrating all of our repos to GitHub Actions. If you are still on Travis or trying to migrate to GitHub Actions, see Travis section.

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

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

alfresco-build-tools

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@v1
        with:
          username: ${{ secrets.DOCKER_USERNAME }}
          password: ${{ secrets.DOCKER_PASSWORD }}

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

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 like Travis.

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.

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

      - 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.

    - 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-unit-tests

Looks for Helm unit tests written using helm3-unittest.

     - uses: >-
         Alfresco/alfresco-build-tools/.github/actions/helm-unit-tests@ref
       with:
         chart-dir: charts/myapp
         chart-type: application

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 }}

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 can be done in a dedicated new workflow:

name: pre-commit

on:
  pull_request:
    branches: [ master ]
  push:

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
      - uses: Alfresco/alfresco-build-tools/.github/actions/pre-commit@ref

This can also be done into an existing workflow, just declaring the step:

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

Both samples require a configuration file .pre-commit-config.yaml to be added to the caller repository.

Note that this action calls the actions/checkout action.

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'

rancher

      - 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:

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):

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:

This message handles use cases where there is only one launch, multiple launches, or when no launches have been 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):

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:

Sample notification on pull_request event:

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"

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

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.

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

setup-kind

Spin up a local kubernetes cluster running in Docker.

      - name: Setup cluster
        uses: Alfresco/alfresco-build-tools/.github/actions/setup-kind@ref
      - name: Helm deploy
        run: |
          helm dep up ./helm/chart
          helm install acs ./helm/chart

travis-env-load

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/travis-env-load@ref
        with:
          ignore_regex: ^BRANCH_NAME=.*
          yml_path: .travis/env.yml

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
        with:
          srcclr-api-token: ${{ secrets.SRCCLR_API_TOKEN }}
          veracode-fails-build: "false"

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 to access an external shared resource, it may be desirable to prevent concurrent builds of the same pull request using concurrency as a top-level keyword:

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

The github.head_ref is available 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 avoid failure when both variables are empty.

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

Run the release script to release a new version from this repository:

./release.sh v1.2.3

opensky-backstage / alfresco-build-tools Goto Github PK