Best Practices Guide - Jenkins as Code

Recommended practices for using Jenkins as Code automation framework

Updated Jan 15, 2024

8 min read

Intermediate

tools

Best Practices Guide

Recommended practices for using Jenkins as Code automation framework

📚 Related Guides:

Setup Guide - Complete Jenkins setup and configuration
JobGenie Job Creation Guide - Step-by-step job creation
Architecture Documentation - System architecture overview
JobGenie Reference - Complete technical reference

⚙️ Configuration Management

1. Use Environment-Specific Variables

✅ DO:

# group_vars/packer_al2023_aarch64_devops_jenkins.yml
jenkins_location:
  url: "https://jenkins-&#123;&#123; environment &#125;&#125;.mcloud.com/"

❌ DON’T:

# Hardcoding values
jenkins_location:
  url: "https://jenkins-prod.mcloud.com/"  # Wrong for all environments

2. Organize Variables Logically

✅ DO:

# Group related variables
jenkins_onboarding:
  amazon:
    mcloud:
      jobs: [ /* ... */ ]
      env: ["nonprod", "prod"]

❌ DON’T:

# Scattered configuration
jenkins_mcloud_jobs: [ /* ... */ ]
jenkins_mcloud_env: ["nonprod", "prod"]
jenkins_amazon_mcloud: [ /* ... */ ]

3. Use Sensible Defaults

✅ DO:

jobgenie:
  default:
    HOME_DIR: prod
    GROUP: "v4"              # Current version group
    ENV: "prod"              # Environment name
  jobs:
    - NAME: "my-service"
      CONFIGS:
        APP_REPO: "my-service"
        APP_BRANCH: "production"

❌ DON’T:

jobgenie:
  default:
    GROUP: null              # No default
    ENV: ""                  # Empty default
  jobs:
    - NAME: "my-service"
      CONFIGS:
        APP_REPO: "hardcoded-repo-name"  # Not flexible

4. Document Custom CONFIGS

✅ DO:

jobgenie:
  default:
    HOME_DIR: prod
    GROUP: "v4"
    ENV: "prod"
  jobs:
    - NAME: "my-service"
      CONFIGS:
        # Custom template for beta features
        # Purpose: Enable template-based Jenkinsfiles for testing
        # Usage: Set CICD_TEMPLATE_NAME to use custom template
        CICD_TEMPLATE_NAME: "beta-template"
        APP_REPO: "my-service"

❌ DON’T:

# Undocumented custom CONFIG
CONFIGS:
  CICD_TEMPLATE_NAME: "beta-template"  # What is this?

🎩 Job Creation

1. Follow Naming Conventions

✅ DO:

jobgenie:
  default:
    HOME_DIR: prod
    GROUP: "v4"
    ENV: "prod"
  jobs:
    - NAME: "user-service"
    - NAME: "payment-service"
    - NAME: "order-service"

❌ DON’T:

# Inconsistent naming
jobs:
  - NAME: "UserService"        # PascalCase
  - NAME: "payment_service"     # snake_case
  - NAME: "orderService"        # camelCase

2. Use Appropriate Job Types

✅ DO:

# Standard pipeline job (default)
jobgenie:
  default:
    HOME_DIR: prod
    GROUP: "v4"
    ENV: "prod"
  jobs:
    - NAME: "my-service"
      CONFIGS:
        APP_REPO: "my-app"
        APP_BRANCH: "master"

# Freestyle job when needed
jobs:
  - NAME: "database-migration"
    CONFIGS:
      JOB_TYPE: "freestyle"
      SERVICE: "database-migration"
      APP_REPO: "migrations"
      SCRIPT: |
        echo "Run migrations"

❌ DON’T:

# Using freestyle for standard application
jobs:
  - NAME: "my-service"
    CONFIGS:
      JOB_TYPE: "freestyle"  # Should use default pipeline
      SCRIPT: |
        # Unnecessary script

✅ DO:

# Group related jobs in one file per environment
# File: amazon/mcloud/prod/jobs/mcloud-prod-jobs.yml
jobgenie:
  default:
    HOME_DIR: prod
    GROUP: "v4"
    ENV: "prod"
  jobs:
    - NAME: "service-1"
      CONFIGS:
        APP_REPO: "app1"
    - NAME: "service-2"
      CONFIGS:
        APP_REPO: "app2"

❌ DON’T:

# Don't create separate files for each job
# Instead, group related jobs together

4. Minimize Job Parameters

✅ DO:

jobs:
  - NAME: "my-service"
    PARAMETERS:
      - { name: 'GitBranch', string: 'production', description: 'Application branch.' }
      - { name: 'DeployVersion', string: 'latest', description: 'Version to deploy.' }
    CONFIGS:
      APP_REPO: "my-service"

❌ DON’T:

jobs:
  - NAME: "my-service"
    PARAMETERS:
      - { name: 'PARAM1', string: '', description: 'Param 1' }
      - { name: 'PARAM2', string: '', description: 'Param 2' }
      - { name: 'PARAM3', string: '', description: 'Param 3' }
      # ... 20 more parameters (too many!)

🔐 Security Practices

1. Use Role-Based Access Control

✅ DO:

# Granular permissions
overall_read_users:
  amazon:
    mcloud:
      - user: "dev"
    qa:
      - user: "qa-user"

❌ DON’T:

# Overly broad permissions
overall_read_users:
  amazon:
    mcloud:
      - user: "*"  # Everyone has access

2. Store Secrets Securely

✅ DO:

Use Jenkins Credentials Plugin
Use AWS Secrets Manager
Use Ansible Vault for sensitive variables

❌ DON’T:

Hardcode passwords in files
Commit secrets to Git
Share credentials via email

3. Regular Security Audits

✅ DO:

Review access permissions quarterly
Audit credential usage
Check for unused credentials
Review audit logs

❌ DON’T:

Set and forget security
Ignore security warnings
Skip access reviews

4. Follow Least Privilege

✅ DO:

# Minimum required permissions
permissionTemplates:
  - name: "build"
    permissions:
      - "Job/Build"
      - "Job/Read"
      - "View/Read"

❌ DON’T:

# Excessive permissions
permissionTemplates:
  - name: "build"
    permissions:
      - "Overall/Administer"  # Too much!
      - "Job/Delete"
      - "Credentials/Manage"

📝 Version Control

1. Use Feature Branches

✅ DO:

# Create feature branch
git checkout -b feature/onboard-new-service

# Make changes
# Commit and push
git commit -m "Onboard new-service-api"
git push origin feature/onboard-new-service

# Create Pull Request

❌ DON’T:

# Direct commits to main
git checkout main
# Make changes
git commit -m "Quick fix"  # No review!
git push origin main

2. Write Meaningful Commit Messages

✅ DO:

git commit -m "Onboard payment-service to mcloud nonprod

- Add payment-service-api to JobGenie
- Configure Docker build args
- Set up ArgoCD integration"

❌ DON’T:

git commit -m "fix"
git commit -m "update"
git commit -m "changes"

3. Review Changes Before Merging

✅ DO:

Create Pull Request
Request review from team
Address feedback
Merge after approval

❌ DON’T:

Merge without review
Skip testing
Ignore feedback

4. Tag Releases

✅ DO:

# Tag stable versions
git tag -a v1.0.0 -m "Initial stable release"
git push origin v1.0.0

❌ DON’T:

Forget to tag releases
Use unclear version numbers
Tag unstable code

📊 Monitoring & Observability

1. Enable Build Notifications

✅ DO:

# Configure notifications in Jenkins system config
jenkins_slack_notifier:
  botUser: false
  room: "devops-alerts"
  teamDomain: "https://yourteam.slack.com/"
  tokenCredentialId: "SlackToken"

❌ DON’T:

# Disable notifications
jenkins_slack_notifier:
  enabled: false  # No visibility

2. Monitor Key Metrics

✅ DO:

Track build success rate
Monitor deployment frequency
Measure mean time to recovery
Track job execution time

❌ DON’T:

Ignore failing builds
Skip monitoring setup
No alerting configured

3. Set Up Logging

✅ DO:

# Enable audit trail
jenkins_audit_trail:
  logBuildCause: true
  logCredentialsUsage: true
  logFile: "/var/log/jenkins/audit-trail.log"

❌ DON’T:

Disable logging
No log retention policy
Logs not centralized

4. Configure Alerts

✅ DO:

Set up build failure alerts
Configure deployment alerts
Monitor system health
Alert on security events

❌ DON’T:

No alerting configured
Ignore alerts
Alert fatigue

🛡️ Disaster Recovery

1. Regular Backups

✅ DO:

# Configure automated backups
jenkins_s3_backup_dir: "s3://bucket-name/backup/jenkins"

❌ DON’T:

No backup strategy
Manual backups only
No backup testing

2. Test Recovery Procedures

✅ DO:

Test full recovery quarterly
Document recovery steps
Verify backup integrity
Practice disaster scenarios

❌ DON’T:

Never test recovery
Outdated documentation
Unknown recovery time

3. Version Control as Source of Truth

✅ DO:

All configs in Git
Git is primary backup
Regular Git backups
Multiple Git remotes

❌ DON’T:

Rely only on Jenkins backups
No Git backup
Single point of failure

👥 Team Collaboration

1. Document Changes

✅ DO:

Update documentation with changes
Add comments for complex logic
Document custom configurations
Maintain changelog

❌ DON’T:

Make undocumented changes
Assume knowledge
Skip documentation

✅ DO:

Conduct training sessions
Share best practices
Document common issues
Create runbooks

❌ DON’T:

Keep knowledge siloed
No knowledge sharing
Tribal knowledge only

3. Standardize Processes

✅ DO:

Use standard templates
Follow naming conventions
Consistent job structure
Standardized workflows

❌ DON’T:

Every team does it differently
No standards
Inconsistent patterns

4. Regular Reviews

✅ DO:

Quarterly architecture reviews
Monthly best practices review
Weekly team sync
Continuous improvement

❌ DON’T:

No regular reviews
Set and forget
No feedback loop

🎯 Performance Optimization

1. Optimize Job Execution

✅ DO:

Use appropriate Jenkins agents
Set build timeouts
Limit concurrent builds
Clean workspace regularly

❌ DON’T:

Run all jobs on master
No timeout limits
Unlimited concurrent builds
Never clean workspace

2. Cache Dependencies

✅ DO:

Cache Docker layers
Cache Maven/Gradle dependencies
Cache Node.js modules
Use build cache

❌ DON’T:

Download dependencies every time
No caching strategy
Slow builds

3. Optimize Resource Usage

✅ DO:

Right-size Jenkins agents
Monitor resource usage
Optimize build scripts
Use efficient tools

❌ DON’T:

Over-provision resources
No resource monitoring
Inefficient builds

📚 Additional Resources

🏠 Main Documentation - Complete Jenkins as Code framework overview
🏗️ Architecture Documentation - System architecture and design
⚙️ JobGenie Guide - JobGenie usage and examples
🚀 DevOps as a Service - Self-service CI/CD platform guide
🔧 Setup Guide - Setup and configuration guide
📝 Quick Reference - Quick reference guide

Related Topics:

Review the Architecture for system design patterns
Learn JobGenie for job creation best practices
See DevOps as a Service for self-service workflows

Maintained by the DevOps Team

“Best practices are not rules, but guidelines for success”

Last Updated: January 15, 2024
Version: 1.0.0

Tags: #Jenkins #Best Practices #CI/CD #Automation #Security #DevOps

Related Tools & Projects

BG Deployer

Automated blue-green deployment for zero-downtime AWS releases

AWS Blue-Green

mCert

SSL certificate monitoring with Slack/email alerts & Telegram

SSL Telegram

mTracker

Real-time Linux user activity monitoring with Slack notifications

Linux Monitoring

mWatcher

Server health monitoring for CPU, memory, disk with alerting

Health Alerts

gCrypt

Git-crypt wrapper for secure file encryption & access management

Security Git-crypt

Interactive Tools

AWS VPC Designer, EKS Cost Calculator, and more utilities

Tools Calculator

External Resources

Official Documentation

AWS Documentation

Complete AWS service documentation

Community Resources

GitHub Profile

Open source projects and repositories

Professional network and updates

Dev.to

Technical articles and tutorials

Contact

Get in touch for questions or collaboration

Quick Actions

All Docs

Browse all documentation

Blog

Tools

DevOps utilities

Portfolio

My work & projects

Found this helpful?

Help us improve this documentation by sharing your feedback or suggesting improvements.

Report Issue Start Discussion

Best Practices Guide

📋 Table of Contents

⚙️ Configuration Management

1. Use Environment-Specific Variables

2. Organize Variables Logically

3. Use Sensible Defaults

4. Document Custom CONFIGS

🎩 Job Creation

1. Follow Naming Conventions

2. Use Appropriate Job Types

3. Group Related Jobs

4. Minimize Job Parameters

🔐 Security Practices

1. Use Role-Based Access Control

2. Store Secrets Securely

3. Regular Security Audits

4. Follow Least Privilege

📝 Version Control

1. Use Feature Branches

2. Write Meaningful Commit Messages

3. Review Changes Before Merging

4. Tag Releases

📊 Monitoring & Observability

1. Enable Build Notifications

2. Monitor Key Metrics

3. Set Up Logging

4. Configure Alerts

🛡️ Disaster Recovery

1. Regular Backups

2. Test Recovery Procedures

3. Version Control as Source of Truth

👥 Team Collaboration

1. Document Changes

2. Share Knowledge

3. Standardize Processes

4. Regular Reviews

🎯 Performance Optimization

1. Optimize Job Execution

2. Cache Dependencies

3. Optimize Resource Usage

📚 Additional Resources

📖 Related Documentation

🧭 Navigation

Related Documentation

More from Tools

Architecture Documentation - Jenkins as Code

DevOps as a Service - Automated CI/CD Management

JobGenie - Complete Job Creation Guide

JobGenie - Complete Guide

Quick Reference Guide - Jenkins as Code

Jenkins as Code - Complete Setup Guide

Jenkins as Code - Enterprise CI/CD Automation

BG Deployer

DevOps Tools & Utilities | Hari Prasad

JobGenie Getting Started

JobGenie

mCert

mTracker

mWatcher

Sample DevOps Tool Documentation

Typography Demo

Related by Tags

Architecture Documentation - Jenkins as Code

DevOps as a Service - Automated CI/CD Management

Related Blog Posts

JobGenie: Transform Jenkins Job Creation with Jobs as Code

OpenResty Production Setup: Supercharge with Lua-Based Metrics and Monitoring

KEDA on EKS: Complete Guide to Event-Driven Autoscaling with Real-World Examples

Related Tools & Projects

BG Deployer

mCert

mTracker

mWatcher

gCrypt

Interactive Tools

External Resources

Official Documentation

AWS Documentation

Community Resources

GitHub Profile