Bitbucket Pipelines with Maven: Complete Guide

Setting Up Your Environment

1. Enable Bitbucket Pipelines

Navigate to your Bitbucket repository settings and enable Pipelines. This will allow you to run automated builds on every push to your repository.

2. Configure Secure Environment Variables

In your Bitbucket repository settings, add these secure environment variables:

• CLOUDREPO_USERNAME: the email address of the CloudRepo member the token belongs to
• CLOUDREPO_API_TOKEN: a repository token, created in the admin portal under Repository Tokens

These variables will be used to authenticate with your private Maven repository without exposing credentials in your code. Revoking a repository token stops that one credential and leaves the rest of the member’s access alone.

Configuration Files

Create bitbucket-pipelines.yml

Add this file to your repository root:

pipelines:
  branches:
    master:
      - step:
          name: Build and Deploy Snapshot Artifact
          script:
            - bash create-settings.sh
            - mvn -B verify
            - mvn -B -s settings.xml deploy

    release/*:
      - step:
          name: Build and Deploy Release Artifact
          script:
            - bash create-settings.sh
            - mvn -B verify
            - mvn -B -s settings.xml deploy

Configure Your POM File

Add distribution management to your pom.xml:

<distributionManagement>
    <repository>
        <id>io.cloudrepo.maven.releases</id>
        <url>https://[your-domain].mycloudrepo.io/repositories/maven-releases</url>
    </repository>
    <snapshotRepository>
        <id>io.cloudrepo.maven.snapshots</id>
        <url>https://[your-domain].mycloudrepo.io/repositories/maven-snapshots</url>
    </snapshotRepository>
</distributionManagement>

Create Settings Generator Script

Create create-settings.sh to write Maven’s settings file:

#!/bin/bash
cat > settings.xml << 'EOF'
<settings>
  <servers>
    <server>
      <id>io.cloudrepo.maven.releases</id>
      <username>${env.CLOUDREPO_USERNAME}</username>
      <password>${env.CLOUDREPO_API_TOKEN}</password>
    </server>
    <server>
      <id>io.cloudrepo.maven.snapshots</id>
      <username>${env.CLOUDREPO_USERNAME}</username>
      <password>${env.CLOUDREPO_API_TOKEN}</password>
    </server>
  </servers>
</settings>
EOF

The quotes around 'EOF' keep the shell from filling in the values. Maven reads ${env.CLOUDREPO_USERNAME} and ${env.CLOUDREPO_API_TOKEN} from the pipeline’s variables when it runs, so the file holds no login.

Deployment Workflow

Snapshot Deployments

Every push to the master branch will:

1. Run tests using mvn verify
2. Deploy snapshot artifacts to your snapshot repository
3. Make artifacts available for other projects immediately

Release Deployments

For release versions:

1. Create a release branch (e.g., release/1.0.0)
2. Update version in pom.xml to remove -SNAPSHOT
3. Push to trigger the release pipeline
4. Tag the release after successful deployment

Validating Your Setup

Check Pipeline Status

After pushing changes:

1. Navigate to Pipelines in your Bitbucket repository
2. Monitor the build progress
3. Check for any errors in the build logs

Verify Artifacts in CloudRepo

1. Log into your CloudRepo account
2. Navigate to your repositories
3. Confirm artifacts appear in the correct repository (snapshots or releases)
4. Verify artifact metadata is correct

Best Practices

Security

• Never commit credentials to your repository
• Use environment variables for sensitive data
• Rotate credentials regularly
• Use repository-specific credentials when possible

Version Management

• Use semantic versioning (MAJOR.MINOR.PATCH)
• Keep snapshot versions on master/develop branches
• Create release branches for stable releases
• Tag releases in Git after successful deployment

Build Optimization

• Cache dependencies to speed up builds
• Run tests in parallel when possible
• Use -B flag for non-interactive builds
• Consider using build profiles for different environments

Troubleshooting

Common Issues

Authentication Failures

• Verify environment variables are set correctly
• Check credentials haven’t expired
• Ensure repository IDs match between POM and settings

Network Issues

• Verify repository URLs are correct
• Check firewall settings
• Ensure HTTPS is used for secure connections

Build Failures

• Review build logs for specific errors
• Run builds locally to reproduce issues
• Check for dependency conflicts

Advanced Configuration

Multi-Module Projects

For projects with multiple modules:

<modules>
    <module>core</module>
    <module>api</module>
    <module>web</module>
</modules>

Configure each module to inherit distribution management from the parent POM.

Custom Deployment Profiles

Create profiles for different deployment scenarios:

<profiles>
    <profile>
        <id>staging</id>
        <distributionManagement>
            <!-- Staging repository configuration -->
        </distributionManagement>
    </profile>
</profiles>

Conclusion

That’s it: every push builds and publishes to CloudRepo. Try it free for 14 days.

Additional Resources

• Example Repository
• Maven Documentation
• Bitbucket Pipelines Documentation
• CloudRepo Documentation