Apache Maven Shared GitHub Actions

current branch is v5

Usage

Create GitHub workflow in project workspace referencing shared maven-verify.yml@v5:

.github/workflows/maven-verify.yml

with content:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

name: Verify

on:
  push:
  pull_request:

jobs:
  build:
    name: Verify
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5

Events that can trigger workflows

In such configuration, workflow can be executed at the same time twice for two separate events.

It can occur when we create PR for branch from the same repository, we have two events:

• push on branch
• pull_request on PR for the same branch

In order to minimize resource consumption, shared workflow from version v2 detect such situation and skip the execution for pull_request event if PR is created for local branch: see #30.

Only workflow for PR from external forks will be executed.

Breaking changes in V3

• replace maven_version by maven-matrix and ff-maven
• rename maven_args to maven-args
• remove not used verify-site-goal

Additional configurations

Attach logs on failure

We can store some logs of execution in case of failure as workflow attachments:

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      failure-upload-path: |
        **/target/surefire-reports/*

Excludes from build matrix

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      matrix-exclude: >
        [ 
          {"jdk": "8"},   # exclude jdk 8 from all builds
          {"os": "windows-latest"}, # exclude windows from all builds
          {"jdk": "8", "os": "windows-latest"} # exclude jkd 8 on windows
        ]

Change default goals

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      ff-goal: 'install'
      verify-goal: 'install -P run-its'

Testing against different Maven versions

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      ff-maven: "3.8.6"                     # Maven version for fail-fast-build
      maven-matrix: '[ "3.2.5", "3.8.6" ]'  # Maven versions matrix for verify builds

Testing with Maven 4

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      maven4-enabled: true
      maven4-version: 'xxx'    # only needed if you want to override default
      verify-goal: 'verify'    # only needed if project doesn't have a run-its profile

Build with Maven 4 only

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      maven4-build: true

Disable matrix build - only fail-fast build

...
    uses: apache/maven-gh-actions-shared/.github/workflows/maven-verify.yml@v5
    with:
      matrix-enabled: false

More options

More options with default values can be found in workflow source in inputs section:

https://github.com/apache/maven-gh-actions-shared/blob/v5/.github/workflows/maven-verify.yml

Release drafter configuration

Only default branch

We need to add an action referencing shared release-drafter.yml@v5:

.github/workflows/release-drafter.yml

with content:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.
   
name: Release Drafter
on:
  push:
    branches:
      - master
  workflow_dispatch:

jobs:
  update_release_draft:
    uses: apache/maven-gh-actions-shared/.github/workflows/release-drafter.yml@v5

and configuration:

.github/release-drafter.yml

with content:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

_extends: maven-gh-actions-shared
tag-template: <project-tag-prefix>-$RESOLVED_VERSION

Multiple versions from multiple branches

We need to change a branch name in .github/workflows/release-drafter.yml in each branch:

name: Release Drafter
on:
  push:
    branches:
      - branch-name # e.g., maven-4.0.x
  workflow_dispatch:

jobs:
  update_release_draft:
    uses: apache/maven-gh-actions-shared/.github/workflows/release-drafter.yml@v5

pre-release, beta versions

To have a pre-release, beta versions we need add to .github/release-drafter.yml

include-pre-releases: true
prerelease: true

Specific configuration per branch

Each branch has its own configuration file in .github/release-drafter.yml.

First release from a new branch

We need to add to .github/release-drafter.yml in branch:

filter-by-commitish: false

When a previous release is not correctly discovered, we can try to filter by version range:

filter-by-range: '>=3.0.0 <4.0.0'

Pull Request Automation

Create GitHub workflow in project file:

.github/workflows/pr-automation.yml

with content:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

name: PR Automation
on:
  push:
    branches:
      - master

jobs:
  pr-automation:
    name: PR Automation
    uses: apache/maven-gh-actions-shared/.github/workflows/pr-automation.yml@v5

From November 2026 the pull_request_target event is disabled for ASF repositories, see ASF GitHub Actions Policy. PR Automation is therefore triggered by push to the branch the PR was merged into, the merged PR is found by the pushed commit.

The workflow is taken from the pushed branch, so it must be present on each branch PRs are merged into, with that branch in the branches list.

After the PR got merged each of the following actions are checked and applied if not already set:

• current milestone will be set unless PR has skip-changelog label
• will be assigned to person who merged PR
• a comment is added and the workflow fails when PR has no label

When PR has skip-changelog label

• current milestone will be removed if was set

A PR closed without merge produces no push, so its milestone is not removed. A PR merged with [ci skip] in the commit message is not processed either.

milestone configuration

We need exactly one open milestone in order to detect which is current.

If we need more than one open milestone, we have to add a branch to the milestone description

branch: <branch name>

This identifies the default for that branch.

PR Check

From November 2026 the pull_request_target event is disabled for ASF repositories, see ASF GitHub Actions Policy. PR Check is therefore triggered by workflow_run after a PR Signal workflow, which runs on pull_request events and only signals that something changed in a PR.

We need two actions in project.

The first one referencing shared pr-signal.yml@v5:

.github/workflows/pr-signal.yml

with content:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

# signal events on PR, will be used by other workflows to trigger actions on PR
# by the workflow_run

name: PR Signal

on:
  pull_request:
    types:
      - edited
      - opened
      - reopened
      - synchronize

jobs:
  pr-signal:
    uses: apache/maven-gh-actions-shared/.github/workflows/pr-signal.yml@v5

The second one referencing shared pr-check.yml@v5:

.github/workflows/pr-check.yml

with content:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

name: PR Check

on:
  workflow_run:
    workflows: [PR Signal]
    types: [completed]

jobs:
  pr-check:
    uses: apache/maven-gh-actions-shared/.github/workflows/pr-check.yml@v5

The workflows list must match the name of the PR Signal workflow.

The PR Check workflow is always taken from the default branch, but the PR Signal workflow is taken from the PR, so it must be present on each branch PRs are opened against. The workflow_run event gives GITHUB_TOKEN with write permission to comment on PRs from forked repositories. The workflow never checks out PR code.

A workflow_run workflow runs on the default branch, so its own checks are not shown on the PR. The result is reported as a commit status on the PR head instead, named PR Check / <job>, e.g. PR Check / license-declaration. The status links to the PR Check run, its summary links back to the checked PR.

In ASF repositories workflows of PRs from external contributors must be approved by a committer, so PR Check is not run and the commit status is not reported until the PR Signal workflow is approved.

The check is run again after editing the PR description or pushing new commits, or by re-running the PR Check run. A re-run of PR Signal with debug logging enabled also dumps the GitHub context to help investigate problems.

Jobs

license-declaration

The PR description must contain at least one checked Apache license declaration:

- [x] I hereby declare this contribution to be licensed under the [Apache License Version 2.0, January 2004](https://www.apache.org/licenses/LICENSE-2.0)
- [x] I hereby declare that I have filed an [Apache Individual Contributor License Agreement](https://www.apache.org/licenses/icla.pdf).

• when declaration is missing - one comment is added and the check fails
• when the description is fixed - the comment is hidden as outdated
• when declaration is removed again - the same comment is restored, never a duplicate

The declaration is not required for PRs opened by bots, by OWNER / MEMBER / COLLABORATOR of the repository and by users with write access to the repository.

Labels synchronization

We can synchronize labels for all Maven repositories by action: Labels sync

Labels list are in file: ./.github/labels.js

Action require GitHub token which will be used for performing updates. Please create new Personal access tokens (classic) with repo scope.

Management of stale issues and PRs

We need an action in project referencing shared stale.yml@v5:

.github/workflows/stale.yml

with body:

# Licensed to the Apache Software Foundation (ASF) under one
# or more contributor license agreements.  See the NOTICE file
# distributed with this work for additional information
# regarding copyright ownership.  The ASF licenses this file
# to you under the Apache License, Version 2.0 (the
# "License"); you may not use this file except in compliance
# with the License.  You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing,
# software distributed under the License is distributed on an
# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
# KIND, either express or implied.  See the License for the
# specific language governing permissions and limitations
# under the License.

name: Stale

on:
  schedule:
    - cron: '15 3 * * *'
  issue_comment:
    types: [ 'created' ]

jobs:
  stale:
    uses: 'apache/maven-gh-actions-shared/.github/workflows/stale.yml@v5'

The cron time definition can be randomly changed to avoid executing at the same time in all project.

Issues and PRs with waiting-for-feedback label

• will be marked as stale after 60 days
• will be closed after next 30 days
• items with milestone or labels priority:blocker, priority:critical will not be checked
• waiting-for-feedback label will be removed after comments

Resources

• Workflow syntax
• Reusing workflows