[FX-4783] Add integration builder how-to guide for GitHub #543
Conversation
✅ Deploy Preview for cobalt-docs ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
TaylorBriggs
force-pushed
the
chore/FX-4783/integration-builder-guide-github-issues
branch
from
f5c8228
to
b2cf2c0
Compare
| @@ -0,0 +1,95 @@ | |||
| --- | |||
| title: "GitHub" | |||
| linkTitle: "GitHub" | |||
There was a problem hiding this comment.
What do you think of naming the article "Push findings to GitHub" instead of just "GitHub"?
|
|
||
| ## Set up the GitHub connection | ||
|
|
||
| 1. Click the create connection button |
There was a problem hiding this comment.
It's probably worth mentioning that they need to navigate to the projects tab first.
|
|
||
|  | ||
|
|
||
| 2. Click on the recipe you want to use and copy it into the folder created in step 5 above. |
There was a problem hiding this comment.
We might move the "copy it into the folder created in step 5 above." part to be above the screenshot that shows the "use this recipe" button. We also might call out that the user needs to click the "use this recipe" button so they know how to do the copy
| 3. You will need to customize the recipe to use your GitHub organization and | ||
| repository. Click the button to customize the recipe, then enter or select your | ||
| organization and repository name in the required fields. Make sure you save the | ||
| recipe after customizing it. |
There was a problem hiding this comment.
then enter or select your organization and repository name in the required fields
For some users to understand this, they will need to be told what action to click on to find the fields they need to fill out
| organization and repository name in the required fields. Make sure you save the | ||
| recipe after customizing it. | ||
|
|
||
|  |
There was a problem hiding this comment.
It would be great if we also told the user how they can customize the content of the GitHub issues the integration creates.
| @@ -0,0 +1,95 @@ | |||
| --- | |||
| title: "GitHub" | |||
There was a problem hiding this comment.
As a generalized feedback: I've found that it helps people figure out where to click if I put a red box around the button they should click in screenshots. I add this using Preview (built into mac) then use the annotate > rectangle tool
|
|
||
| ## Test the recipe | ||
|
|
||
| To test the recipe with pentest findings, follow the guide for |
There was a problem hiding this comment.
I might have missed it, but I couldn't find instructions on where/how to change the pentest for which issues should be created. The "Edit the recipe" section comes close to that, but doesn't explicitly mention that the pentest can be selected there.
There was a problem hiding this comment.
I didn't even think about this. @grayson-cobalt can correct me if I'm wrong, but I believe it will fire for all pentests/findings within the org by default.
I just looked at it more carefully and the trigger can be set to fire for either a specific asset or a pentest. There are also trigger conditions, but that already links out to external documentation so I'm not sure I need to add anything about that.
I'll add a section for how to update the trigger.
There was a problem hiding this comment.
Ah ok, I wasn't aware the trigger worked for the whole org as well. Then there's probably no need to mention it, maybe just a note.
|
@mahmoudadly-cobalt @wolfgangbecker I made a folder for |
Yes, I saw that and applied it to #544 as well. I agree this is better to keep things organized. |
grayson-cobalt
deleted the
chore/FX-4783/integration-builder-guide-github-issues
branch
Changelog
Added
Preview This Change
To see how this change looks in production, scroll down to Deploy Preview. Select the link that looks like
https://deploy-preview-<num>--cobalt-docs.netlify.app/Variables
Help us support a “Write once, publish everywhere” single source of truth. If you see a line that looks like:
{{% asset-categories %}}You’ve found a shortcode that we include in multiple documents.
You’ll find the content of the shortcode in the following directory:
https://github.com/cobalthq/cobalt-product-public-docs/tree/main/layouts/shortcodes
That shortcode has the same base name as what you see in the PR, such as
asset-categories.html.Checklist for PR Author
[ ] Did you check for broken links and alt text?
Be sure to check for broken links and Alt Text issues. We have a partially automated process,
as described in this section of our repository README:
Test Links and Alt Attributes.