Connect to Jenkins

You can start automatic builds with Jenkins triggers and Secure Source Manager webhooks.

Required roles

To get the permissions that you need to create Jenkins build triggers, ask your administrator to grant you the following IAM roles:

Secure Source Manager Repo Admin ( roles/securesourcemanager.repoAdmin ) on your repository
Secure Source Manager Instance Accessor ( roles/securesourcemanager.instanceAccessor ) on the Secure Source Manager instance

For more information about granting roles, see Manage access to projects, folders, and organizations .

You might also be able to get the required permissions through custom roles or other predefined roles .

For information on granting Secure Source Manager roles, see Access control with IAM and Grant users instance access .

Set up a webhook trigger

Jenkins uses build trigger plugins to enable CI/CD automation. You can configure triggers to listen for incoming events, such as when a new commit is pushed to a repository or when a pull request is initiated, and then automatically execute a build when new events come in. You can also configure triggers to build code on any changes to your source repository or only on changes that match certain criteria.

To set up a generic Jenkins webhook Trigger:

Install the Jenkins Git Plugin , SSH Credential Plugin and Generic Webhook Trigger Plugin on your Jenkins server.
Generate a valid SSH key pair in your Jenkins server. Secure Source Manager only supports RSA type keys.
Add the Secure Source Manager instance domain to the Jenkins server SSH known_hosts file by running the following command:
```
 ssh  
-t  
git@ INSTANCE_ID 
- INSTANCE_PROJECT_NUMBER 
-ssh.us-central1.sourcemanager.dev 
```
Where:
- INSTANCE_ID is the name of your Secure Source Manager instance.
- INSTANCE_PROJECT_NUMBER is the project number of your Secure Source Manager instance. See Identifying projects for information on where to find your project number.
For example, the following command adds the instance domain for an instance named prod-test-instance with a project number of 123456789 .
```
 ssh  
-t  
git@prod-test-instance-123456789-ssh.us-central1.sourcemanager.dev 
```
Reply yes to add the instance domain to the list of known hosts.
In the Jenkins Manage Credentialspage:
1. Select SSH username with private key.
2. Paste in your Jenkins server SSH private key.
3. In the Kinddrop-down, fill in the other fields as required.
Click Create.
In the Jenkins web interface, create a new Jenkins job.
In the Jenkins job's configuration page, under the Source Code Managementsection, select Git.
In the Gitsection, paste the Secure Source Manager repository SSH URL as the Repository URL, enter your build branches (e.g. */main ), and then select the saved private SSH key credential that you added previously in the Manage Credentialspage.
In the Build Triggerssection, select Generic Webhook Trigger.

Optionally, you can add a token so that the job is only triggered if that token is supplied when invoking. To add a token, under the Generic Webhook Triggersection, you can input a token in the Tokenfield.
In the Buildsection, provide a build script you would like to have for this Jenkins job. For example, you can execute cat README.md to print the content of README.md.
Click Saveto create the Jenkins job.

Set up a service account and grant required permissions

If you don't already have a service account that you want to use, create a service account .

Ensure you have the iam.serviceAccounts.actAs permission on the service account. This permission is part of the Service Account User ( roles/iam.serviceAccountUser ) role.
In the Secure Source Manager web interface, click the more optionsmenu.
Click Service account SSH keys. The Service account SSH keyspage opens, and a list of any existing keys you've added is displayed.
Click Add key.
In the Add SSH keypage, enter the following values for your key:
1. Service account: the service account email for the service account you want to use the SSH key with in the format SA_NAME @ PROJECT_ID .iam.gserviceaccount.com
  
  Where
  - SA_NAME is the service account name.
  - PROJECT_ID is the project ID of the project the service account was created in.
2. SSH Public Key: Your Jenkins public SSH key.

Grant the Secure Source Manager service agent permissions

If the service account is not in the same project as your Secure Source Manager instance you must also grant the Secure Source Manager service agent the Service Account Token Creator ( roles/iam.serviceAccountTokenCreator ) role or iam.serviceAccounts.signJwt permission.

If your service account is in the same project as your Secure Source Manager instance, skip to Grant the service account a repository role .

Run the following command to get the existing IAM policy for your service account:
```
 gcloud  
iam  
service-accounts  
get-iam-policy  
 SERVICE_ACCOUNT 
  
 \ 
  
--format  
json 
```
Where SERVICE_ACCOUNT is the service account you want to use. The account should be formatted either as a numeric service account ID or as an email, like this: 123456789876543212345 or my-iam-account@somedomain.com .

The output includes any existing bindings, or, if none exist, the etag value similar to the following:
```
  { 
 "etag" 
:  
 "BwUjHYKJUiQ=" 
 } 
 
```
Important: keep the etag value from the get-iam-policy response to ensure that you don't overwrite someone else's policy changes. If you want to overwrite all other changes, you can remove the etag value.
Copy the output into a new file named policy.json .
To grant the Secure Source Manager service agent the Service Account Token Creator ( roles/iam.ServiceAccountTokenCreator ) role, modify the policy.json to add the following:
```
  { 
  
 "role" 
:  
 "roles/iam.serviceAccountTokenCreator" 
,  
 "members" 
:  
 [ 
  
 "serviceAccount:service- INSTANCE_PROJECT_NUMBER 
@gcp-sa-sourcemanager.iam.gserviceaccount.com" 
  
 ] 
 } 
 
```
Where INSTANCE_PROJECT_NUMBER is the project number of your Secure Source Manager instance.
Run the following command to replace the existing IAM policy for the service account:
```
 gcloud  
iam  
service-accounts  
set-iam-policy  
 SERVICE_ACCOUNT  
 POLICY_FILE 
 
 
  
```
Replace the following:
- SERVICE_ACCOUNT with the service account ID or email.
- POLICY_FILE with the location and name of the JSON formatted file including the new policy.

Grant the service account a repository role

In the Secure Source Manager web interface, navigate to the repository you want to give the service account permissions in.
Click the Permissionstab.
Click Add Users.
In the Add principalfield, enter the service account email address.
In the Roledrop-down menu, select Secure Source Manager Repository Reader.
Assign the service account the securesourcemanager.instanceAccessor role by running the following command:
```
 gcloud  
projects  
add-iam-policy-binding  
 PROJECT_ID 
  
 \ 
  
--member = 
serviceAccount: SA_EMAIL 
  
 \ 
  
--role = 
roles/securesourcemanager.instanceAccessor 
```
Replace the following:
- PROJECT_ID with the Secure Source Manager instance project ID.
- SA_EMAIL with the service account email.

Set up a webhook

In the Secure Source Manager web interface, navigate to the repository you want to create a webhook for.
Click Settings.
Click Webhooks, and then click Add webhook.
In the Hook IDfield, enter an ID for the webhook.

Note: Hook IDs must follow the resource naming convention . They must include only lower case letters, numbers, or dashes, must begin with a letter, and cannot be changed after creating the webhook.
In the Target URLfield, enter the Jenkins Trigger URL.
If you used the optional token when configuring your Jenkins trigger, then the Jenkins trigger URL will contain that token at the end. To prevent leaking the token, remove it from the end of the target URL and copy to the Sensitive Query Stringfield.

To locate your token in your trigger URL, look for the text starting with token=

For example, if your URL resembles the following: https://jenkins-server.com/generic-webhook-trigger/invoke?token=jenkins-job1

Copy and remove the portion starting with the question mark ?token=jenkins-job1 portion from the Target URLfield. Then remove the initial question mark, move the remaining portion token=jenkins-job1 to the Sensitive Query Stringfield.
In the Trigger onsection, select one of the following:
- Push: to trigger on a push to the repository.
- Pull request state changed: to trigger on a change in the pull request state.
If you selected Push, then you can enter an allowlist for push events in the Branch filterfield.

The Branch filterfield uses the glob pattern and only operations on the matched branches will cause a build trigger. If the field is empty or * , then push events for all branches are reported.
Click Add webhook.
The webhook is displayed in the Webhookspage.

Note: When you add or edit a webhook, the length of the Sensitive Query String might be inconsistent with the entered one, which is expected as placeholder strings are used to ensure security.

Test your webhook

In the Secure Source Manager Webhookspage, click the webhook you want to test.
Go to the bottom of the page and click Test delivery.

A fake event is added to the delivery queue. It might take a few seconds before it shows up in the delivery history.
You can also use a git command to push or merge a pull request to test the webhook.
In the Jenkins project, view the build triggered by the test event in Build History.
You can also view the Requestand Responseto the test delivery in the Recent deliveriessection of the Secure Source Manager webhook page after you send your first test delivery.

What's next

Explore the Jenkins documentation .