diff --git a/images/jenkins-management-guide/authorization-chart.jpg b/images/jenkins-management-guide/authorization-chart.jpg new file mode 100644 index 0000000..cb841b5 Binary files /dev/null and b/images/jenkins-management-guide/authorization-chart.jpg differ diff --git a/jenkins-management-guide.md b/jenkins-management-guide.md new file mode 100644 index 0000000..70e847f --- /dev/null +++ b/jenkins-management-guide.md @@ -0,0 +1,169 @@ +# **Jenkins Management Guide** + +## Introduction + +Jenkins is a widely used open-source automation server that facilitates continuous integration and continuous deployment (CI/CD). This guide is designed to help team leaders understand how to use Jenkins to build and deploy game projects efficiently. It covers how to create, set up, and manage new build jobs, ensuring stability, security, and streamlined development workflows. + +## Authentication + +Ensuring secure access to Jenkins is crucial for maintaining project integrity and preventing unauthorized changes. Only the HoD has permission to configure authentication settings, ensuring centralized control over user access. + +### Authentication Methods + +**Built-in Jenkins User Database**: The default authentication method where users are managed directly in Jenkins. User accounts are provided and managed by HoD. + +### Steps to Create a New User in Jenkins + +1. **Log in to Jenkins** as HoD. +2. Navigate to **Manage Jenkins** > **Users**. +3. Click on **Create User**. +4. Fill in the required details: + - **Username**: A unique identifier for the user. + - **Password**: A secure password for authentication. + - **Full Name**: The user’s full name. + - **Email Address**: Used for notifications and communication. +5. Click **Create User** to finalize the process. + +### Authorization +- **HoD**[^1]: Full administrative access with capabilities to manage security settings and user accounts. Can create, modify, and oversee build jobs. +- **Team Leaders**: Can only trigger build jobs and view results and logs. +- **Anonymous**: Can only view build results and logs. + +![Authorization Chart](images\jenkins-management-guide\authorization-chart.jpg) + +### Steps to Change Authorization + +1. **Log in to Jenkins** as the HoD. +2. Navigate to **Manage Jenkins** > **Security**. +3. Locate the **Authorization** section. +4. Select **Matrix-based security** if not already enabled. +5. Modify user or group permissions by checking or unchecking relevant boxes: + - Grant or restrict access to specific Jenkins features. + - Ensure only authorized users have administrative privileges. +6. Click **Save** to apply the changes. + +--- + +## Jenkins Agents + +Jenkins agents are used to distribute build and deployment workloads across multiple machines, improving performance and scalability. Agents allow Jenkins to execute tasks on different platforms or dedicated environments. + +### Steps to Set Up a Jenkins Agent + +1. **Log in to Jenkins** as the HoD. +2. Navigate to **Manage Jenkins** > **Nodes**. +3. Click **New Node** and provide a name for the agent. +4. Select **Permanent Agent** and click **OK**. +5. Configure environment variables or tools if required. +6. Click Save to finalize. + +### Steps to Start the Jenkins Agent + +1. Navigate to **Manage Jenkins** > **Nodes**. +2. Select the offline agent from the list. +3. Go to the **Status** tab of the selected agent +4. Follow the guide provided there to start the agent. +5. Verify that the agent status changes to Online in the Dashboard. + +--- + +## Creating and Managing Jobs + +Jenkins jobs define the tasks for building, testing, and deploying projects. + +### Steps to Create a New Job + +1. **Log in to Jenkins** as the HoD. +2. Click **New Item** from the Jenkins dashboard. +3. Enter a **Job Name** that reflects the purpose of the build. +4. Select the appropriate job type. +5. Click **OK** to create the job. +6. Configure the job settings: + - **Add Build Parameters**: Configure dynamic input parameters for builds. + - **Define a Custom Workspace**: Specify a custom directory for build execution. + - **Allow Remote Build Triggering**: Enable builds to be triggered via remote requests. + - **Add Build Step with Windows Batch Command**: + - Click **Add Build Step**. + - Select **Execute Windows Batch Command**. + - Enter the batch script commands required for the build process. + - Click **Save**. +7. Click **Save** to finalize the job configuration. + +### Steps to Trigger a Build Job + +#### Using the Jenkins UI + +1. **Log in to Jenkins**. +2. Navigate to the **Jenkins Dashboard**. +3. Select the desired job from the list and click on it to open the job details page. +4. If the job has parameters, fill in the required values in the parameter fields before proceeding. +4. Click on **Build Now**. +5. Monitor the build progress in the **Build History** section. +6. Click on a specific build to view detailed logs and console output. + +#### Triggering a Build Remotely + +1. Use a web request (such as `curl` or Postman) to trigger the build: + ```sh + curl --user JENKINS_USERNAME:JENKINS_PASSWORD --location --request GET "http://your-jenkins-server/job/YOUR_JOB_NAME/buildWithParameters?token=YOUR_SECRET_TOKEN&PARAM_NAME=PARAM_VALUE" + ``` +2. Check the **Build History** section to verify that the job has started. +3. Monitor the build progress and logs as needed. + +--- + +## Setting Up Notifications for Microsoft Teams + +Integrating Jenkins with Microsoft Teams allows build notifications to be sent directly to a Teams channel, keeping the team informed of build statuses. + +### Steps to Configure Microsoft Teams Notifications + +1. **Create an Incoming Webhook in Microsoft Teams**: + - Open Microsoft Teams and navigate to the desired channel. + - Click on **More Options (⋮)** > **Connectors**. + - Search for **Incoming Webhook** and click **Add**. + - Provide a name for the webhook and upload an optional image. + - Click **Create** and copy the generated webhook URL. +#### +2. **Configure Job to Send Notifications**: + - Open the desired job in Jenkins. + - Click **Configure**. + - Scroll down to the **Office 365 Connector / Power Automate workflows** section. + - Paste the Microsoft Teams webhook URL copied earlier. + - Configure the message format and triggers (e.g., on build success, failure, etc.). + - Click **Save**. + +--- + +## Builder Script +The Builder Script is a step-by-step script that automates the entire process of building a project. It is designed to guide Jenkins through each phase of the build process, ensuring that each task, such as retrieving dependencies, compiling code, and packaging the final product, is done in the correct order. This script is useful for maintaining a consistent build process, improving automation, and minimizing human error during development. + +By integrating this script into your Jenkins job, you can ensure that every project build follows the same structured procedure, making it easier to manage and debug builds when necessary. + +### Repository Url +https://gitea.plp19.com/dev-tools/p4f-project-builder.git + +### Add Initial Build Step to Clone and Update the Builder Script +You need to add the following code as the first build step in every Jenkins build job to ensure that the latest version of the builder script is used and that all dependencies are correctly set up before proceeding with the build process. + +```sh +echo off +set BUILDER_PATH="C:\Tools\p4f-project-builder" + +if not exist %BUILDER_PATH% ( + git clone https://jenkins:jenkins@gitea.plp19.com/dev-tools/p4f-project-builder.git %BUILDER_PATH% +) + +cd %BUILDER_PATH% +git add --a +git reset --hard +git checkout develop +git fetch +git pull +call npm install +cd %WORKSPACE% + +exit /b 0 +``` + +[^1]: Head of Department \ No newline at end of file