Access a Project's Git Repositories
You can configure a job to access a project’s Git repositories and their source code files:
-
Open the job's configuration page.
- Click the Git tab.
- From the Add Git list, select Git.
- 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. - 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. - Click Save.
If you specify multiple Git repositories, make sure that you set Local Checkout Directory for all Git repositories.
Run 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.
- 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:
- Open the job’s configuration page.
- 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.
- For the Git repository you want to monitor, select the Automatically perform build on SCM commit check box.
- To include or exclude files when tracking changes in the
repository, click the Include or
Exclude button, then enter the names of one or more
branches, a pattern (like
valid.-*
), or both in the Branches field. See Generate Cron Expressions for more information on entering patterns.Note:
If you choose to run this job manually using the Build Now button, we'll show you a list of all the branches in your repo that match the Include/Exclude criteria so you can pick one to build. For example, if your Include criteria isbranch*
andtest*
, then we'll show you all the branches that begin with those terms. If you specified Exclude instead, we'll show all the branches that don't begin with those terms—likely quite a few. If we don't find a branch that matches, we'll build your default branch instead. - 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:
- Open the job’s configuration page.
- 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.
- Click Settings .
- Click the Triggers tab.
- Click Add Trigger and select SCM Polling Trigger.
- 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.
- 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.
- 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/
or1/
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. - If necessary, in Comment, enter a comment.
- 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.
- 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 as1-5
-
/
or*/X
to specify skips of X's value through the range, such as0/15
in theMINUTE
field for0,15,30,45
-
A,B,...,Z
can be used to specify multiple values, such as0,30
or1,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.
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:
- Open the job’s configuration page.
- Click the Git tab.
- 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 themyapp/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 themyapp/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 nottest.java
:*.java test.java A build runs when any .java
file is changed, except whentest.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
andtest.html
) triggers a build.Don’t trigger a build when .java
files in the/myapp/mobile/
directory are changed, with the exception oftest.java
:/myapp/mobile/*.java test.java
A build won't run when all changes are in .java
files other thantest.java
in the/myapp/mobile/
directory. But a build runs whentest.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 themyapp/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 themyapp/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.
- 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.
- 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:
Access Files in a Git Repository's Private Branch
To access a Git repository's private branch, configure the job to use SSH:
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.
To publish Git artifacts to a Git repository:
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 from the Git tab of the job configuration page. To see all configuration actions, expand the Advanced Repository Options and Advanced Git Settings sections.
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 |
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. Be sure that directory names don't contain a forward slash or null character. You can optionally include parameters in the path, such as:
If Local Checkout Directory is 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.
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 If necessary, in Checkout revision, specify the branch to checkout and build as |
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 |
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.