Access a Project's Git Repositories

You can configure a job to access a project’s Git repositories and their source code files:

1. Open the job's configuration page.

2. Click the Git tab.
3. From the Add Git list, select Git.
4. In Repository, select the Git repository to track.

   When you created the job, if you selected the Use for Merge Request check box, the field is automatically populated with the ${GIT_REPO_URL} value. Don’t change it.

5. In Branch, select the branch name in the repository to track. By default, main is set.

   When you created the job, if you selected the Use for Merge Request check box, Branch is automatically populated with the ${GIT_REPO_BRANCH} value. Don’t change it unless you don’t want to link the job with a merge request.

6. Click Save.

If you specify multiple Git repositories, make sure that you set Local Checkout Directory for all Git repositories.

Trigger a Build Automatically on an SCM Commit

You can configure a job to monitor a Git repository and trigger a build automatically each time a commit is pushed.

There are different use cases in which an automatically-triggered build will work and other cases where you should set up a polling job instead:

• A trigger that's set up to build automatically on an SCM commit only works with repositories that are defined and stored in the same project. In this case, commits to Git repositories in your project are sufficient triggers for automatically initiating a build.
• An automatic trigger for a build job isn't recommended for an external repository. In this case, a polling job should be set up. Only a git push operation will result in a build.
• An automatic trigger for a build job isn't recommended for an external repository that has been cloned as an internal repository either. In this case, a polling job should be set up. Only a git push operation will result in a build.

To set up a polling-based build trigger, see Trigger a Build Automatically According to an SCM Polling Schedule.

Here's how to configure a job that monitors a Git repository in your project and triggers a build automatically when a Git commit is pushed to the repository being tracked:

1. Open the job’s configuration page.
2. Click the Git tab and either use the dropdown to select the repository you want to monitor or type the name of the repository in the entry field.
3. For the Git repository you want to monitor, select the Automatically perform build on SCM commit check box.
4. To include or exclude files when tracking changes in the repository, see Include or Exclude Files to Trigger a Build.
5. To exclude users whose commits to the repository don’t trigger builds, in Excluded User, enter the list of user names.
6. Click Save.

Trigger a Build Automatically According to an SCM Polling Schedule

SCM polling enables you to configure a job to periodically check the job’s Git repositories for any commits pushed since the job’s last build. If updates are found, it triggers a build. You can configure the job and specify the schedule in Coordinated Universal Time (UTC), the primary time standard by which the world regulates clocks and time. If you’re not a Cron expert, use the novice mode and set the schedule by specifying values. If you’re a Cron expert, use the Expert mode.

You can specify the schedule using Cron expressions:

1. Open the job’s configuration page.
2. In the Git tab, add the Git repository.

   To include or exclude files when tracking changes in the repository according to a Cron expression, see Include or Exclude Files to Trigger a Build.

3. Click Settings .
4. Click the Triggers tab.
5. Click Add Trigger and select SCM Polling Trigger.
6. To use the expert mode, select the Expert mode check box and enter the schedule in the text box.

   The default pattern is 0/30 * * * *, which runs a build every 30 minutes.

   After you edit the expression, it’s validated immediately when the cursor moves out of the text box. Note that other fields of the section aren’t available when the check box is selected.

7. To use the novice mode, deselect the Expert mode check box and specify the schedule information. The page displays the generated Cron expression next to the Expert mode check box.
8. To use the novice mode, deselect the Expert mode check box and specify the schedule information in Minute, Hour, Day of the Month, Month, and Day of the Week.

   Click Toggle Recurrence to add or remove 0/or 1/ at the beginning of the value in the Cron expression.

   The page displays the generated Cron expression next to the Expert mode check box.

   Tip:

   To check the job’s Git repositories every minute, deselect all check boxes. Remember that this may consume large amounts of system resources.
9. If necessary, in Comment, enter a comment.
10. To view and verify the build schedule of the next ten builds, from the timezone drop-down list, select your time zone and then click View Schedule.
11. Click Save.

To see the SCM poll log of the job after the build runs, in the job's details page or the build's details page, click SCM Poll Log .

Generate Cron Expressions

You can use Cron expressions to define periodic build patterns.

For more information about Cron, see http://en.wikipedia.org/wiki/Cron.

You can specify the Cron schedule information in the following format:

MINUTE HOUR DOM MONTH DOW

where:

• MINUTE is minutes within the hour (0-59)

• HOUR is the hour of the day (0-23)

• DOM is the day of the month (1-31)

• MONTH is the month (1-12)

• DOW is the day of the week (1-7)

To specify multiple values, you can use the following operators:

• * to specify all valid values

• - to specify a range, such as 1-5

• / or */X to specify skips of X's value through the range, such as 0/15 in the MINUTE field for 0,15,30,45

• A,B,...,Z can be used to specify multiple values, such as 0,30 or 1,3,5

Include or Exclude Files to Trigger a Build

When you've configured a job to monitor a Git repository, you can use fileset patterns to include or exclude files when tracking changes in the repository. Then, each time a change is committed, only changes to files that match these patterns determine whether a build is triggered or not.

Fileset patterns work as filters to include or exclude files when tracking changes in a repository. They take effect only when you've enabled a build to be triggered either on each SCM commit or according to a polling schedule. Once these settings are enabled, each time changes are committed to the repository, the filter is applied and a build either runs or not based on the specified filter.

Here's how you specify fileset patterns that use changes to files that match these patterns to determine whether a build is triggered or not:

1. Open the job’s configuration page.
2. Click the Git tab.
3. Expand Advanced Git Settings and select either Include or Exclude.
   • Click Include to specify a list of files and directories in the repository that you want to track for changes. By default, all files are included for tracking (**/*), meaning changes to any file or directory in the repository will trigger a build.

     To change the default configuration, select Include and specify the fileset to be included in Directories/Files. You can use regular expressions (regex) or glob patterns to specify the fileset. Each entry must be separated by a new line.

     You can extend this configuration to specify Exceptions to the included fileset. If changes occur only in the fileset specified as an exception, a build won't run.

     Here are some glob pattern examples:

     Desired Outcome	In Directories/Files, enter:	In Exceptions, enter:	Result
     Trigger a build following changes to .html, .jpeg, or .gif files in the myapp/src/main/web/ directory:	myapp/src/main/web/*.html myapp/src/main/web/*.jpeg myapp/src/main/web/*.gif	Leave blank	A build runs when a .html, .jpeg, or .gif file is changed in the myapp/src/main/web/ directory.
     Trigger a build following changes to .java files, but not .html files:	*.java	*.html	A build runs when any .java file is changed, except when all changed files are .html files.
     Trigger a build following changes to .java files, but not test.java:	*.java	test.java	A build runs when any .java file is changed, except when test.java is the only changed file.

   • Click Exclude to specify a list of files and directories in the repository that you don't want to track for changes. If all changes are only in the specified files, a build won’t be triggered. By default, no files are excluded, meaning all files and directories are tracked and therefore, changes to any file or directory in the repository will trigger a build.

     To change the default configuration, select Exclude and specify the fileset to be excluded in Directories/Files. You can use regular expressions (regex) or glob to specify an excluded fileset. Each entry must be separated by a new line.

     Optionally, specify files or directories within the excluded fileset that you want to include as Exceptions. If changes occur in the fileset specified as an exception, a build will be triggered.

     Here are some glob pattern examples:

     Desired Outcome	In Directories/Files, enter:	In Exceptions, enter:	Result
     Don’t trigger a build when only .java files are changed:	*.java	Leave blank	A build won't run when all changed files are .java files, but changes in any other file (say, test.txt and test.html) triggers a build.
     Don’t trigger a build when .java files in the /myapp/mobile/ directory are changed, with the exception of test.java:	/myapp/mobile/*.java	test.java	A build won't run when all changes are in .java files other than test.java in the /myapp/mobile/ directory. But a build runs when test.java in the /myapp/mobile/ directory is the only changed file.
     Don't trigger a build for changes to any file, except .sql files:	**/*	*.sql	A build runs only when .sql files are changed.
     Don’t trigger a build when only .html, .jpeg, or .gif files in the myapp/src/main/web/ directory are changed:	myapp/src/main/web/*.html myapp/src/main/web/*.jpeg myapp/src/main/web/*.gif	Leave blank	A build won't run when only .html, .jpeg, or .gif files in the myapp/src/main/web directory are changed.
     Don’t trigger a build when .gitignore files are changed:	*.gitignore	Leave blank	A build won't run when the only changed files are .gitignore files.

4. Click Save.

Use External Git Repositories

If you use an external Git repository to manage source code files, you can configure a job to access its files when a build runs:

• If the external Git repository is a public repository, mirror it in the project or use its direct URL in the job configuration.
• If the external Git repository is a private repository, you must mirror it in the project. See Mirror an External Git Repository.

To configure a job to use an external Git repository:

1. Open the job’s configuration page.
2. Click the Git tab.
3. From the Add Git list, select Git.
4. If the external Git repository is mirrored with the project, in Repository, select the repository name. The build executor will use the mirrored repository's internal address URL.
   If the external Git repository isn't mirrored with the project, enter the repository's direct URL. Don't enter the direct URL of a private repository.
5. Configure other fields of the page and click Save.

To trigger a build on an update to the external Git repository, set up SCM polling according to the frequency of commits. VB Studio can't trigger a build immediately on an update to the external Git repository.

Before you set SCM polling, note that if you use the internal address URL of a mirrored repository, there's a wait time of at least 5 minutes. If you use the external address URL or the direct URL of the repository, there's a wait time of at least 1 minute. Remember that polling every few minutes consumes large amounts of system resources.

Access Files in a Git Repository's Private Branch

To access a Git repository's private branch, configure the job to use SSH:

1. On the computer that you'll use to access the Git repository, generate a SSH key pair and upload its private key to VB Studio. See Upload Your Public SSH Key. Make sure that the private key on your computer is accessible to the Git client.
   Ignore this step if you've already uploaded the SSH public key.
2. Copy the Git repository’s SSH URL.

   On the Git page, from the Repositories drop-down list, select the Git repository. From the Clone drop-down list, click Copy to clipboard and copy the SSH URL:

   
   Description of the illustration devcs_code_clone.png
3. Open the job’s configuration page.
4. Click the Git tab.
5. From the Add Git list, select Git.
6. In Repository, paste the SSH URL of the Git repository.
7. In Branch, select the private branch.
8. Click the Before Build tab.
9. Click Add Before Build Action and select SSH Configuration.
10. In Private Key and Public Key, enter the private and public key of your SSH Private-Public key pair.
    Leave the Public Key empty to use fingerprint.
11. In Pass Phrase, enter the pass phrase of your SSH Private-Public key pair. Leave it empty if the keys aren’t encrypted with a pass phrase.
12. Continue to configure the job, as desired.
13. Click Save.

Publish Git Artifacts to a Git Repository

You can set up a post-build action to publish Git artifacts, such as tags, branches, and merge results, to a Git repository.

Before publishing any artifacts to a Git repository, you're encouraged to review Best Practices for Storing Large Files and Binaries. The information should help you determine the best way to handle generated artifacts in your project, especially if they are generated frequently.

To publish Git artifacts to a Git repository:

1. Open the job’s configuration page.
2. In the Git tab, add the Git repository where you want to publish Git artifacts.
3. Click the After Build tab.
4. Click Add After Build Action and select Git Publisher.
5. To push Git artifacts to the Git repository only if the build succeeds, select the Publish only if build succeeds check box.
6. To push merges back to the target remote name, select the Merge results check box.
7. To push a tag to the remote repository, in Tag to push, specify the Git repository tag name. You can also use environment variables. In Target remote name, specify the target remote name of the Git repository where the tag is pushed. By default, origin is used.

   The push fails if the tag doesn’t exist. Select the Create new tag check box to create the tag and enter a unique tag name.

8. To push a branch to the remote repository, in Branch to push, specify the Git repository branch name. You can also use environment variables. In Target remote name, specify the target remote name of the Git repository where the branch is pushed. By default, origin is used.
9. Click Save.

Advanced Git Options

When you configure a job's Git repositories, you can also configure several advanced Git options, such as changing the remote name of the repository, setting the checkout directory in the workspace, and specifying whether or not the workspace is cleaned before a build runs.

You can select and enable these configuration actions after expanding the Advanced Repository Options from the Git tab of the job configuration page:

Action	How To
Change the remote name of a repository	For the Git repository, specify the new name in Name. The default remote name is origin.
Specify a reference specification of a repository	A reference repository helps to speed up the builds of the job by creating a cache in the workspace and hence reducing the data transfer. When a build runs, instead of cloning the Git repository from the remote, the build executor clones it from the reference repository. To create a reference specification of a Git repository, specify the name in Ref Spec. Leave the field empty to create a default reference specification.
Specify a local checkout directory	The local checkout directory is a directory in the workspace where the Git repository is checked out when a build runs. To specify the directory of a Git repository, specify the path in Local Checkout Directory. If left empty, the Git repository is checked out on the root directory of the workspace.
Include or exclude a list of files and directories to determine whether to trigger a build or not	When you've enabled a build to be triggered either on each SCM commit or according to a polling schedule, select Include or Exclude. To include a list of files and directories to track for changes and trigger a build, click Include and specify a fileset in Directories/Files. Default is **/*, indicating that all files and directories in the repository are tracked and changes to any file or directory will trigger a build. If you don't want a build to be triggered for some files and directories in the included fileset, specify Exceptions. For example, to trigger a build following changes to all but .java files, enter **/* in Directories/Files and *.java in Exceptions. To exclude a list of files and directories from tracking and prevent a build from being triggered, click Exclude and specify a fileset in Directories/Files. If all changes occur only in the specified files or directories, a build won’t run. Default is an empty list, indicating no files are excluded. If you want a build to be triggered for some files and directories in the excluded fileset, specify Exceptions. For example, to trigger a build only when .sql files are changed, enter **/* in Directories/Files and *.sql in Exceptions. For more examples, see Include or Exclude Files to Trigger a Build.
Check out the remote repository’s branch and merge it into a local branch	In Merge another branch, specify the branch name to merge to. If specified, the build executor checks out the revision to build as HEAD on this branch. If necessary, in Checkout revision, specify the branch to checkout and build as HEAD on the value of Merge another branch.
Configure Git user.name and user.email variables	In Config user.name and Config user.email, specify the user name and the email address.
Merge to a branch before a build runs	Select the Merge from another repository check box. In Repository, enter or select the name of the repository to be merged. In Branch, enter or select the name of the branch to be merged. If no branch is specified, the default branch of the repository is used. The build runs only if the merge is successful.
Prune obsolete local branches before running a build	Select the Prune remote branches before build check box.
Set the depth for cloning	Select the Use shallow clone check box and then choose from 1-8192 commits to grab when you clone. For example, to clone with the three most recent commits, select a value of 3. The Depth default is 1, except for YAML jobs, where the default depth is 0. Selecting a low depth can speed up your build process as less data needs to be fetched from the Git repository before the build. The default setting is a full depth job.
Skip the internal tag	When a build runs, the build executor checks out the Git repository to the local repository of the workspace and applies a tag to it. To skip this process, deselect Skip internal tag check box.
Remove untracked files before running a build	Select the Clean after checkout check box.
Retrieve sub-modules recursively	Select the Recursively update submodules check box.
Display commit’s author in the log	By default, the Git change log shows the commit’s Committer . To display commit’s Author, select the Use commit author in changelog check box.
Delete all files of the workspace before a build runs	Select the Wipe out workspace before build check box.

View the SCM Changes Log

The SCM changes log displays files that were added, edited, or removed from the job’s Git repositories before the build was triggered.

You can view the SCM changes log from the job’s details page and a build’s details page. The Recent SCM Changes page that you open from the job’s details page shows SCM commits from the last 20 builds, in reverse order. The SCM Changes page that you open from a build’s details page shows SCM commits that happened after the previous build.

The log shows the build ID, commit messages, commit IDs, and affected files.