Tag-Based Deployment in Jenkins CI/CD Using GitHub — A Practical Guide

🧠 Introduction

In modern CI/CD pipelines, tag-based deployment is a smart and reliable way to release versioned software.
Instead of deploying every commit or branch push, we deploy only when a Git tag is created — like v1.0, release-qa, or prod-1.2.

This ensures that only tested and verified code reaches the target environment (QA, staging, or production).
It also improves traceability, rollback control, and release management.

In this guide, we’ll walk through how to:

Set up Jenkins to work with GitHub

Trigger a build when a tag is pushed

Build and deploy only tagged versions automatically

⚙️ Step 1: Prerequisites

Before you start, make sure you have:

A running Jenkins server (for example, on Amazon Linux 2)

Git plugin and Pipeline plugin installed on Jenkins

GitHub credentials (Personal Access Token or SSH key)

A GitHub repository: https://github.com/username/repo.git

A target environment to deploy your application (like a QA EC2 instance or Docker setup)

🧱 Step 2: Create a Git Tag

Clone your repository and create a tag:

git clone https://github.com/username/repo.git
cd etoe
git tag -a v1.0 -m "Release version 1.0"
git push origin v1.0

Once pushed, the tag will serve as your deployment trigger.

🧰 Step 3: Create a Jenkins Pipeline Job

1. Open your Jenkins dashboard and click “New Item”.

2. Enter a name, for example, etoe-tag-deploy, and choose Pipeline.

3. In the configuration page, under Build Triggers, check the box for
   GitHub hook trigger for GITScm polling.

4. In the Pipeline section:

Set the Definition to “Pipeline script from SCM”.

Select Git as SCM.

Set the repository URL to https://github.com/username/repo.git.

Choose your GitHub credentials.

Set Branches to build as ** (this includes all branches and tags).

Enter Jenkinsfile as the script path.

Save the job configuration.

🌐 Step 4: Configure the GitHub Webhook

Now connect GitHub and Jenkins.

1. Go to your GitHub repository.

2. Click Settings → Webhooks → Add Webhook.

3. In the Payload URL, enter your Jenkins webhook endpoint, for example:
   http://:8080/github-webhook/

4. Choose application/json as the content type.

5. Select “Just the push event”.

6. Click Add Webhook.

Now Jenkins will be notified whenever a push (including tags) occurs.

🧾 Step 5: Create the Jenkinsfile

Create a file named Jenkinsfile in the root of your repository.

pipeline {
agent any

triggers {
    githubPush()   // Trigger when GitHub pushes occur (branch or tag)
}

stages {
    stage('Checkout') {
        steps {
            echo "Cloning repository and checking for tag..."
            checkout([$class: 'GitSCM',
                branches: [[name: '**']],
                userRemoteConfigs: [[
                    url: 'https://github.com/username/repo.git',
                    credentialsId: 'github-creds'
                ]]
            ])

            script {
                // Detect if this build was triggered by a tag
                def tagName = sh(script: "git describe --tags --exact-match || echo 'no-tag'", returnStdout: true).trim()
                if (tagName == 'no-tag') {
                    echo "Not a tag build, skipping deployment."
                    currentBuild.result = 'SUCCESS'
                    error("Stopping pipeline: not a tag push.")
                } else {
                    env.TAG_NAME = tagName
                    echo "Detected Tag: ${env.TAG_NAME}"
                }
            }
        }
    }

    stage('Build') {
        when { expression { return env.TAG_NAME != null } }
        steps {
            echo "Building application for ${env.TAG_NAME}"
            // Replace this with your actual build process
            sh 'mvn clean package -DskipTests'
        }
    }

    stage('Deploy to QA') {
        when { expression { return env.TAG_NAME != null } }
        steps {
            echo "Deploying tag ${env.TAG_NAME} to QA environment..."
            // Replace this with your actual deployment command
            sh '''
            ssh ec2-user@<qa-server> "
                cd /opt/etoe &&
                git fetch --tags &&
                git checkout ${TAG_NAME} &&
                ./deploy.sh
            "
            '''
        }
    }
}

post {
    success {
        echo "Deployment successful for ${env.TAG_NAME}"
    }
    failure {
        echo "Deployment failed for ${env.TAG_NAME}"
    }
}

}

🔍 Step 6: How This Pipeline Works

When a tag is pushed to the GitHub repository:

1. The GitHub webhook triggers the Jenkins job.

2. Jenkins checks out the latest code and detects if the commit is associated with a tag.

3. If a tag is detected, Jenkins sets an environment variable TAG_NAME.

4. The build stage compiles or packages the application for that specific tag.

5. Finally, the deploy stage runs deployment commands for that tagged version.

If no tag is found, the pipeline exits gracefully without deploying.

🧪 Step 7: Test the Complete Flow

Let’s verify the setup by creating a new tag:

git tag -a v1.1 -m "QA Release 1.1"
git push origin v1.1

Once the tag is pushed:

Jenkins automatically triggers the pipeline.

You’ll see the tag name printed in the logs.

The build and deploy stages execute for that tag.

🧩 Optional: Add Manual Approval for Production

If you want to add a confirmation step before deploying to production, you can use an input step:

stage('Approval for Production') {
when { expression { return env.TAG_NAME != null } }
steps {
timeout(time: 5, unit: 'MINUTES') {
input message: "Deploy ${env.TAG_NAME} to Production?", ok: "Proceed"
}
}
}

This ensures human approval before a production deployment happens.

💡 Why Tag-Based Deployment?

Tag-based deployments offer multiple advantages:

You always know which version of code is deployed.

Deployments are intentional and controlled, not triggered by every commit.

You can easily roll back to a specific version using the tag.

Each deployment is traceable to a Git version for auditing.

🏁 Conclusion

You’ve now implemented a full tag-based CI/CD pipeline using Jenkins and GitHub.
From the moment a developer pushes a new tag, Jenkins automatically detects it, builds, and deploys the tagged version — all without manual intervention.

This setup brings consistency, traceability, and control to your software delivery process.