Secure Partner Integration - Onboarding Process
If you want to integrate your product with the Secure Stage, this page will help you understand the developer workflow GitLab intends for our users to follow with regards to security results. These should be used as guidelines so you can build an integration that fits with the workflow GitLab users are already familiar with.
This page also provides resources for the technical work associated with onboarding as a partner. The steps below are a high-level view of what needs to be done to complete an integration as well as linking to more detailed resources for how to do so.
What is the GitLab Developer Workflow?
This workflow is how GitLab users interact with our product and expect it to function. Understanding how users use GitLab today will help you choose the best place to integrate your own product and its results into GitLab.
- Developers want to write code without using a new tool to consume results or address feedback about the item they are working on. Staying inside a single tool, GitLab, helps them to stay focused on finishing the code and projects they are working on.
- Developers commit code to a Git branch. The developer creates a merge request (MR) inside GitLab where these changes can be reviewed. The MR triggers a GitLab pipeline to run associated jobs, including security checks, on the code.
- Pipeline jobs serve a variety of purposes. Jobs can do scanning for and have implications for app security, corporate policy, or compliance. When complete, the job reports back on its status and creates a job artifact as a result.
- The Merge Request Security Widget displays the results of the pipeline’s security checks and the developer can review them. The developer can review both a summary and a detailed version of the results.
- If certain policies (such as merge request approvals) are in place for a project, developers must resolve specific findings or get an approval from a specific list of people.
- The security dashboard also shows results which can developers can use to quickly see all the vulnerabilities that need to be addressed in the code.
- When the developer reads the details about a vulnerability, they are
presented with additional information and choices on next steps:
- Create Issue (Confirm finding): Creates a new issue to be prioritized.
- Add Comment and Dismiss Vulnerability: When dismissing a finding, users can comment to note items that they have mitigated, that they accept the vulnerability, or that the vulnerability is a false positive.
- Auto-Remediation / Create Merge Request: A fix for the vulnerability can be offered, allowing an easy solution that does not require extra effort from users. This should be offered whenever possible.
- Links: Vulnerabilities can link out external sites or sources for users to get more data around the vulnerability.
How to onboard
This section describes the steps you need to complete to onboard as a partner and complete an intgration with the Secure stage.
- Read about our partnerships.
- Create an issue using our new partner issue template to begin the discussion.
- Get a test account to begin developing your integration. You can request a GitLab.com Gold Subscription Sandbox or an EE Developer License.
- Provide a pipeline job template that users could integrate into their own GitLab pipelines.
- Create a report artifact with your pipeline jobs.
- Ensure your pipeline jobs create a report artifact that GitLab can process
to successfully display your own product’s results with the rest of GitLab.
- See detailed technical directions for this step.
- Read more about job report artifacts.
- Read about job artifacts.
- Your report artifact must be in one of our currently supported formats.
For more information, see the documentation on reports.
- Documentation for SAST reports.
- Documentation for Dependency Scanning reports.
- Documentation for Container Scanning reports.
- See this example secure job definition that also defines the artifact created.
- If you need a new kind of scan or report, create an issue
and add the label
devops::secure
.
- Once the job is completed, the data can be seen:
- In the Merge Request Security Report (MR Security Report data flow).
- While browsing a Job Artifact.
- In the Security Dashboard (Dashboard data flow).
- Optional: Provide a way to interact with results as Vulnerabilities:
- Users can interact with the findings from your artifact within their workflow. They can dismiss the findings or accept them and create a backlog issue.
- To automatically create issues without user interaction, use the issue API. This will be replaced by Standalone Vulnerabilities in the future.
- Optional: Provide auto-remediation steps:
- If you specified
remediations
in your artifact, it is proposed through our auto-remediation interface.
- If you specified
- Demo the integration to GitLab:
- After you have tested and are ready to demo your integration please reach out to us. If you skip this step you won’t be able to do supported marketing.
- Begin doing supported marketing of your GitLab integration.
- Work with our partner team to support your go-to-market as appropriate.
- Examples of supported marketing could include being listed on our Security Partner page, doing an Unfiltered blog post, doing a co-branded webinar, or producing a co-branded whitepaper.
If you have any issues while working through your integration or the steps above, please create an issue to discuss with us further.
Help and feedback
If there's something you don't like about this feature
To propose functionality that GitLab does not yet offer
To further help GitLab in shaping new features
If you didn't find what you were looking for
If you want help with something very specific to your use case, and can use some community support
POST ON GITLAB FORUM
If you have problems setting up or using this feature (depending on your GitLab subscription)
REQUEST SUPPORT
To view all GitLab tiers and features or to upgrade
If you want to try all features available in GitLab.com
If you want to try all features available in GitLab self-managed
If you spot an error or a need for improvement and would like to fix it yourself in a merge request
EDIT THIS PAGE
If you would like to suggest an improvement to this doc