Checks out your project from a Git repository using the Jenkins Git plugin.

stages {
    git.sync()
    // ...
}

With overrides:

stages {
    git.sync(
        GIT_BRANCH: 'develop'
    )
    // ...
}

• Plugin: Git plugin (usually pre-installed)
• Credential: Git credential in Jenkins for private repos (see Credential Setup below)

1. Clones or fetches from the Git repository
2. Checks out the specified branch
3. Sets ctx.vcsType = 'Git' and ctx.revision (commit hash) for downstream stages

For private repositories, create a credential in your team's Jenkins folder.

For HTTPS repositories:

• Kind: Username with password
• Username: your Git username
• Password: a personal access token (not your actual password)
• ID: e.g., git-myproject

GitHub no longer accepts account passwords for Git operations. You need a Personal Access Token (PAT) instead. Fine-grained tokens are recommended over classic tokens because they allow you to limit access to specific repositories and permissions.

1. Go to github.com/settings/personal-access-tokens/new
2. Fill in:
   • Token name: a descriptive name (e.g., Jenkins - MyProject)
   • Expiration: choose an expiration period (or Custom for a longer duration — note the security trade-off)
   • Resource owner: select the organization that owns the repository (e.g., BredaUniversityGames)
3. Under Repository access, select Only select repositories and pick the repository that Jenkins will build
4. Under Permissions > Repository permissions, set:
   • Contents: Read-only (or Read and write if the pipeline needs to push/tag or create releases with github.release())
   • Metadata: Read-only (selected by default)
5. Click Generate token
6. Copy the token immediately — it won't be shown again

Use this token as the Password field when creating the Jenkins credential.

Note: If the organization requires approval for fine-grained tokens, an organization admin must approve the token before it can be used. You'll see the token status as "pending" until approved.

For SSH repositories:

• Kind: SSH Username with private key
• Username: git
• Private Key: paste your SSH private key
• ID: e.g., git-ssh-myproject

1. Download and install PuTTY (includes PuTTYgen)

2. Open PuTTYgen from the Start menu

3. At the bottom, select EdDSA as the key type (or RSA with 4096 bits if EdDSA is not available)

4. Click Generate and move your mouse over the blank area to generate randomness

5. Once generated:

   • Optionally set a Key passphrase for extra security (you'll enter it in Jenkins when creating the credential)
   • In the Key comment field, enter a description (e.g., jenkins-myproject)

6. Save the public key for GitHub:

   • Select and copy the entire text in the Public key for pasting into OpenSSH authorized_keys file box at the top of the window (starts with ssh-ed25519 or ssh-rsa)
   • Save this somewhere temporarily — you'll need it for the next step

7. Export the private key in OpenSSH format (Jenkins requires OpenSSH format, not PuTTY's .ppk):

   • Go to Conversions > Export OpenSSH key
   • When warned about saving without a passphrase, click Yes
   • Save the file (e.g., jenkins_myproject)

8. Open the exported private key file in a text editor (e.g., Notepad). Copy the entire contents (including the -----BEGIN and -----END lines).

Step 1 — Add the private key to Jenkins:

1. Navigate to your team's folder in Jenkins
2. Click Credentials > (folder) > Global credentials > Add Credentials
3. Fill in:
   • Type: SSH Username with private key
   • ID: optionally enter a unique name for your credential. Something like git-ssh-myproject. If you leave this blank, a unique ID will be generated for your credential.
   • Description: An optional description. The description will help you identify this credential.
   • Username: git
   • Private Key: select Enter directly, click Add, and paste the private key contents
   • Passphrase: enter the passphrase if you set one in PuTTYgen (leave empty otherwise)
4. Click Create

Step 2 — Add the public key to GitHub:

1. Go to your repository on GitHub
2. Navigate to Settings > Deploy keys
3. Click Add deploy key
   • Title: e.g., Jenkins
   • Key: paste the public key you copied from PuTTYgen (the ssh-ed25519 ... line)
   • Check Allow write access only if the pipeline needs to push
4. Click Add key

Alternatively, for access to multiple repositories, add it as an account-level SSH key at github.com/settings/keys.

Tip: Deploy keys are preferred over account-level keys because they limit access to a single repository, following the principle of least privilege.

For GitHub App authentication (recommended for organizations):

GitHub Apps provide higher API rate limits (scale with organization size vs. the fixed 5,000/hour for PATs), fine-grained permissions, and don't tie credentials to a personal account. This makes them ideal for shared CI environments.

Requires the GitHub Branch Source plugin.

1. Go to your GitHub organization's settings: github.com/organizations/BredaUniversityGames/settings/apps/new

   Important: You must create the app from the organization's settings page, not your personal account settings. Apps created under a personal account can only be installed on your own repositories.

2. Fill in:

   • GitHub App name: e.g., Jenkins - BUAS
   • Homepage URL: your Jenkins server URL or repository URL
   • Webhook: deselect the Active checkbox (not needed if Jenkins polls for changes)

   Optional: If your Jenkins server is publicly accessible and you want instant build triggers on push, leave webhooks active and set the URL to https://<your-jenkins-host>/github-webhook/.

3. Set Permissions:

   • Contents: Read-only (or Read & Write if the pipeline needs to push/tag)
   • Metadata: Read-only (mandatory, selected by default)

   Optional — enable these if you want Jenkins to report build status on GitHub commits/PRs:

   • Commit statuses: Read & Write
   • Pull requests: Read-only

4. Under Subscribe to events, leave all events unchecked (event subscriptions are only needed if you enabled webhooks)

5. Under Where can this GitHub App be installed?, select Only on this account

6. Click Create GitHub App

7. On the app's settings page, note the App ID (displayed near the top)

8. Scroll down to Private keys and click Generate a private key — a .pem file will download

Jenkins requires the key in PKCS#8 format. On Windows, use Git Bash (included with Git for Windows) or WSL:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in downloaded-key.pem -out jenkins-github-app.pem -nocrypt

Open jenkins-github-app.pem in a text editor and copy the entire contents.

1. Go to your GitHub App's settings page
2. Click Install App in the left sidebar
3. Click Install next to your organization
4. Select Only select repositories
5. Use the dropdown to pick the repository that Jenkins will build
6. Click Install

1. Navigate to your team's folder in Jenkins
2. Click Credentials > (folder) > Global credentials > Add Credentials
3. Fill in:
   • Kind: GitHub App
   • ID: e.g., github-app-myteam
   • App ID: the App ID from the GitHub App settings page
   • Key: click Add, paste the converted private key contents
4. Under Test Connection, enter BredaUniversityGames in the GitHub organization to test against field
5. Click Test Connection to verify the credential works
6. Click Create

Use this credential ID wherever the pipeline requires a Git credential.