Deployment jobs

Business feature

Only workspaces under Business plan can access the Deployment jobs feature.

Introduction

Deployment jobs are a key feature enabling the efficient dissemination of honeytokens across multiple code repositories. This process involves creating pull requests to insert a file containing a honeytoken into the targeted repositories.

During a deployment job, for each selected repository, GitGuardian will:

1. Create a unique honeytoken.
2. Place it within an appropriate file context.
3. Create a pull request to insert the honeytoken into the repository.

It's important to note that the decision to merge each honeytoken into the main branch rests with the user, who must perform this action directly in the VCS. GitGuardian's function is limited to opening the pull request. In any case, you should consider the honeytoken as deployed as soon as the pull request is created, since it is now visible in the git repository.

info

We use "Pull request" universally across all Version Control Systems (VCSs). For GitLab, this is equivalent to "Merge requests".

Prerequisites

info

Currently, this feature supports GitLab and GitHub sources only. Azure DevOps and BitBucket are not supported at present.

To use deployment jobs, GitGuardian requires write access to the repositories being monitored.

• For GitLab projects: No extra setup is needed.
• For GitHub and GitHub Enterprise repositories: Additional steps are required to enable write permissions. See detailed instruction in the integration guides for GitHub or GitHub Enterprise.

Creating a deployment Job

Navigate to the “Deployment jobs” tab within the Honeytoken module and click Create deployment job.

1. Name: Assign a descriptive name to your deployment job, indicating its scope or purpose.
2. Context creation strategy: Choose a strategy for the types of files to be used for honeytoken insertion. Details on the context creation strategies are available in a dedicated section.
3. Labels: Assign labels to the honeytokens generated in this job, aiding in identification and filtering. For example, auto-deploy:true could denote honeytokens created from deployment jobs.
4. Sources: Select the repositories where you wish to deploy honeytokens.

info

Some sources might not be eligible for deployment jobs, including Azure DevOps, BitBucket, GitHub repositories without write permissions, sources outside the monitored perimeter, and public sources. Refer to the help section for troubleshooting.

Note: The number of sources selected cannot exceed the number of available honeytokens for creation.

Context creation strategy

In the Honeytoken settings, you can view and modify context creation strategies. These strategies determine the file types into which honeytokens may be inserted, classified as either "generic" or "dynamic":

info

“Generic” refer to file types that could realistically be found in any repository, irrespective of programming language, such as .env, .txt, .csv, .yaml, .json.
“Dynamic” refer to file types and content aligned with the main language of the target repository. Our dynamic contexts are generated by AI using the requested language. Note that no code is ever sent to the model.

When creating or editing a strategy, you must select a "context creation" option, as well as the generic context types that you want to allow:

Even when selecting the “Dynamic contexts” option, you still need to select at least one type of generic context: should the repository language not be existing or available, the system will fallback on a generic file.

Follow the progress of your Deployment job

Once a deployment job is created, you can view the status of each individual deployment:

• Processing: The pull request is pending.
• Pull request created: GitGuardian has successfully created the honeytoken and the pull request.
• Merged: The proposed change has been approved and merged.
• Pull request closed: The proposed change has been declined, closing the pull request.
• Error: An issue occurred during deployment (details available in the side panel upon clicking the deployment).

For statuses other than “Processing” and “Error,” you'll find links to the honeytoken, the pull request, and the inserted file.

It's important to note that a honeytoken is considered deployed once the pull request is created, as it becomes visible in the repository, irrespective of whether it's merged. If a pull request is closed, the honeytoken remains unless the branch and pull request are explicitly deleted.

Characteristics of honeytokens created from deployment jobs

Honeytokens created via deployment jobs have the following characteristics:

• The name: Corresponds to the source name, appended with a suffix based on the deployment job
• Labels: As specified during the deployment job creation.
• Link: When the source is detected and the information added to the honeytoken (shortly after the pull request is created), there is a link to redirect to the associated deployment.