Administration guide for setting up and configuring a Jenkins server for BUAS game development projects. This guide covers plugin installation, security configuration, credential management, and multi-tenant isolation for student teams.

Install these plugins via Manage Jenkins > Plugins > Available plugins:

Optional plugins depending on which stages you use:

JenkinsLib must be configured as a Global Trusted Pipeline Library so it can run outside the Groovy sandbox. This is required for features like auto-detecting installed UE5 engine versions.

1. Go to Manage Jenkins > System
2. Scroll to Global Trusted Pipeline Libraries and click Add
3. Configure:
   • Name: JenkinsLib — identifier used in @Library('JenkinsLib') in Jenkinsfiles
   • Default version: main (or dev for testing) — the branch, tag, or commit to use
   • Load implicitly: unchecked — pipelines must explicitly load the library with @Library
   • Allow default version to be overridden: checked — lets Jenkinsfiles specify a different branch/tag
   • Include @Library changes in job recent changes: checked — shows library changes in build history
   • Cache fetched versions on controller for quick retrieval: checked — avoids re-fetching from Git on every build
     • Cache refresh time in minutes: 1440 (1 day)
     • Versions to exclude: dev (exclude branches under active development from caching)
   • Retrieval method: Modern SCM
   • Source Code Management: Git
   • Project Repository: https://github.com/BredaUniversityGames/JenkinsLib
   • Credentials: leave empty for public repositories, or select a credential for private ones
   • All other settings (Behaviors, Library Path) can be left at their defaults
4. Click Save

Important: The library must be loaded in the Jenkinsfile using the @Library annotation (not the library() step) for trusted execution to apply. See the example Jenkinsfile for the correct syntax: @Library('JenkinsLib') _

Use Jenkins Folders to isolate student teams. Each folder gets its own credential store, preventing teams from accessing each other's credentials.

Jenkins
├── Team-Alpha/              (Folder)
│   ├── Credentials          (only visible to Team-Alpha jobs)
│   │   ├── p4-alpha         (Perforce credential)
│   │   └── steam-alpha      (Steam credential)
│   └── Alpha-Build          (Pipeline job)
├── Team-Beta/               (Folder)
│   ├── Credentials          (only visible to Team-Beta jobs)
│   │   ├── p4-beta
│   │   └── discord-beta
│   └── Beta-Build
└── Shared/                  (Folder - optional)
    └── Credentials          (shared credentials, if any)

1. Click New Item
2. Enter the team name (e.g., Team-Alpha)
3. Select Folder
4. Click OK

All pipeline jobs and credentials for that team go inside this folder.

See the Credentials page for full setup instructions covering Perforce tickets, Git PATs, SSH keys, GitHub Apps, and service credentials.

JenkinsLib pipelines expect a Windows build agent.

• Windows 10/11 or Windows Server
• Node label: Windows (the pipeline uses node('Windows') — see Setting the Node Label below)
• Tools installed on the agent:
  • Perforce CLI (p4.exe) if using perforce.sync()
  • Unreal Engine 5 if using ue5.build()
  • Visual Studio / MSBuild if using vs.build()
  • SteamCMD if using steam.deploy()
  • Butler if using itch.deploy()
  • BuildPatchTool if using epic.deploy()
  • sentry-cli if using sentry.upload()

The pipeline runs on a node with the label Windows. You must assign this label to your build agent.

For a new agent:

1. Go to Manage Jenkins > Nodes > New Node
2. Enter a name (e.g., build-agent-01), select Permanent Agent, click Create
3. In the Labels field, enter Windows
4. Configure the remaining fields (remote root directory, launch method, etc.)
5. Click Save

For an existing agent:

1. Go to Manage Jenkins > Nodes
2. Click the agent name
3. Click Configure in the left sidebar
4. Add Windows to the Labels field (space-separated if there are other labels)
5. Click Save

Tip: The built-in controller node can also have labels. Go to Manage Jenkins > Nodes > Built-In Node > Configure and add Windows to the labels. This is useful for single-machine setups but not recommended for production — use a dedicated agent instead.

Configure these environment variables on each build agent under Manage Jenkins > Nodes > (node) > Configure > Node Properties > Environment variables:

The pipeline uses a fixed workspace path: C:\Jenkins\<JOB_NAME>. This is hardcoded in vars/stages.groovy and overrides Jenkins' default workspace. It ensures workspace reuse between builds for faster incremental syncs (especially for Perforce, where only changed files are synced).

This path is not configurable through Jenkins — it is set by the pipeline itself. The only requirement is that the Jenkins agent has write access to C:\Jenkins\.

For a multi-student environment, use one of these authorization strategies:

This is included with Jenkins by default (via the Matrix Authorization Strategy plugin, usually pre-installed).

1. Go to Manage Jenkins > Security
2. Under Authorization, select Project-based Matrix Authorization Strategy
3. Add your admin user and grant Administer permissions
4. Add an Authenticated Users entry with minimal global permissions:
   • Overall: Read
   • Job: none at the global level (permissions are set per-folder)
5. Click Save

Then configure per-folder permissions:

1. Navigate to a team's folder (e.g., Team-Alpha)
2. Click Configure
3. Under Properties, check Enable project-based security
4. Add the team members and grant:
   • Job: Build, Cancel, Read
   • Run: Replay, Update
   • SCM: Tag
5. Click Save

Repeat for each team folder. Students will only see folders where they have been explicitly granted access.

Install the Role-based Authorization Strategy plugin for a more structured approach.

1. Go to Manage Jenkins > Security
2. Under Authorization, select Role-Based Strategy
3. Click Save
4. Go to Manage Jenkins > System
5. Check Restrict project naming
6. Select Role-Based Strategy
7. Click Save

This prevents users from creating projects outside the naming patterns defined in their roles.

Create roles:

1. Go to Manage Jenkins > Manage and Assign Roles > Manage Roles
2. Under Global roles, create:
   • admin — grant Overall: Administer (implies all other permissions)
   • viewer — grant only Overall: Read
3. Under Item roles, create a role per team:
   • Role name: team-alpha
   • Pattern: Team-Alpha/.* (matches all jobs inside the Team-Alpha folder)
   • Grant: Job: Build, Cancel, Read; Run: Replay, Update
4. Click Save

Assign roles:

1. Go to Manage Jenkins > Manage and Assign Roles > Assign Roles
2. Under Global roles, assign admin to administrators and viewer to all students
3. Under Item roles, assign each student to their team's role
4. Click Save

This ensures:

• Students can only see and run their own team's jobs
• Students cannot view or use other teams' credentials
• Students cannot modify Jenkins system settings

• All student credentials are folder-scoped (not global)
• Each team has its own folder
• Students don't have access to Manage Jenkins > Credentials
• Perforce tickets are per-team (not a shared service account, unless intentional)
• Global credentials (if any) contain only shared, non-sensitive items

Under Manage Jenkins > System > Usage Statistics or per-job configuration:

• Keep last 5-10 builds (game builds are large)
• Discard old builds to save disk space

• Set executors per agent based on available CPU/RAM
• UE5 builds are resource-intensive — 1-2 executors per agent is typical
• VS builds are lighter — 2-4 executors may work

Configure per-job under job configuration:

• Poll SCM: check for changes on schedule (e.g., H/15 * * * * for every 15 min)
• Webhook: configure Git/Perforce to notify Jenkins on push/submit
• Build periodically: fixed schedule (e.g., H 2 * * * for nightly at 2 AM)