Skip to content

Continuous integration servers

axion-release-plugin was designed to be CI friendly, which meant adding some custom features. However, CI build plans need to be configured in certain way. Below are guides for tested CI servers.

CI servers is treated as trusted environment, thus there is no harm in disabling checks that need to interact with git (like uncommitted files check or ahead of remote check).

Jenkins

Jenkins and axion-release cooperate nicely. However, because Jenkins will check out git repositories in a detached head state, two flags should be set when running the release task:

./gradlew release -Prelease.disableChecks -Prelease.pushTagsOnly

Disabling checks is necessary because axion-release is not able to verify if current commit is ahead of remote. Setting pushTagsOnly ensures that git will not throw an error by attempting to push commits while not working on a branch.

To use the versionWithBranch version creator from Jenkins, you need to override the default behavior of the Jenkins git plugin to avoid the detached-head state. In the Git section of the job configuration page, add the Additional Behaviour called Check out to matching local branch.

Jenkins pipeline now defaults to clone with a narrow refspec, and without tags (as of git plugin 3.4.0). That saves network bandwidth, time, and disc space. If you need tags in your Jenkins workspace, add the Additional Behaviour called Advanced clone behaviors. Adding that behaviour will enable fetching of tags.

Bamboo

Enable tags fetch

Bamboo fetches bare minimum of information from git. By default, it won't even fetch tags. To change this:

  • go to plan configuration
  • open Repositories tab
  • choose code repository
  • open Advanced options
  • disable Use shallow clones option

Attach remote on build

Bamboo does not fetch remotes list. Fortunately axion-release can attach itself to the remote using remote address passed via Bamboo variables:

./gradlew release -s \
    -Prelease.attachRemote=${bamboo.repository.git.repositoryUrl} \
    -Prelease.disableChecks

We also need to disable checks, as there is no way to verify if current commit is ahead of remote.

Bitbucket Pipelines

Bitbucket Pipelines allow to commit to repository without any configuration. However, it requires git client to use local proxy. It can be configured by passing following parameters:

./gradlew release -Dhttp.proxyHost=localhost -Dhttp.proxyPort=29418

Azure DevOps Pipelines

Azure Pipelines will check out git repositories in a detached head state. That is why two flags should be set when running the release task:

./gradlew release -Prelease.disableChecks -Prelease.pushTagsOnly

Disabling checks is necessary because axion-release is not able to verify if current commit is ahead of remote. Setting pushTagsOnly ensures that git will not throw an error by attempting to push commits while not working on a branch.

To use features related to branches (like versionWithBranch, branchVersionIncrementer or branchVersionCreator) you need to override branch name with overriddenBranchName flag and set it to Build.SourceBranch Azure Pipelines predefined variable:

./gradlew release \
    -Prelease.disableChecks \
    -Prelease.pushTagsOnly \
    -Prelease.overriddenBranchName=$(Build.SourceBranch)

GitHub Actions

Your workflow needs to use actions/checkout@v3 with configuration to fetch tags:

steps:
  - uses: actions/checkout@v3
    with:
      fetch-depth: 0

When you have a lot of tags/commit you can speed up your build - plugin successfully works using local git shallow repository, but you must run git fetch --tags --unshallow before running ./gradlew release - that will ensure the plugin has all the info it needs to run.

steps:
    - uses: actions/checkout@v3
    - name: Publish using Axion
      run: |
          # Fetch a full copy of the repo, as required by release plugin:
          git fetch --tags --unshallow
          # Run release:
          ./gradlew release

In order to push tags into the repository release step must use GitHub actor and token:

  - name: Release
    id: release
    run: |
      ./gradlew release \
          -Prelease.customUsername=${{ github.actor }} \
          -Prelease.customPassword=${{ github.token }}

GitHub token requires write permissions to push tags into the repository. To grant GitHub token write permissions use Settings -> Actions -> General -> Workflow permissions -> Read and write permissions option.

GitLab CI

If you set up a project token you can easily add a non-user dependent tag stage. Add the project token and token user bot name as CI-variables, accessible to the build script.

Example:

tagging:
  stage: tag
  image: ....
  script:
   - git remote set-url origin ${CI_SERVER_URL}/${CI_PROJECT_NAMESPACE}/${CI_PROJECT_NAME}.git
   - ./gradlew release -Prelease.disableChecks -Prelease.pushTagsOnly -Prelease.overriddenBranchName=${CI_COMMIT_BRANCH} -Prelease.customUsername=${PROJECT_ACCESS_TOKEN_BOT_NAME} -Prelease.customPassword=${PROJECT_ACCESS_TOKEN}

NOTE: You need to set the git remote url first, as GitLab's default cloned project url will have added the non repo-write permission gitlab-ci-token to the origin url.

Disabling checks is necessary because axion-release is not able to verify if current commit is ahead of remote. Setting pushTagsOnly ensures that git will not throw an error by attempting to push commits while not working on a branch.

Since Gitlab will do a detached head checkout, the branch name has to be overridden when versionWithBranch is used.