-
Notifications
You must be signed in to change notification settings - Fork 0
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
enh: add documentation for snap-in build config #41
Open
navneel99
wants to merge
16
commits into
main
Choose a base branch
from
nav/ISS-84458
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 11 commits
Commits
Show all changes
16 commits
Select commit
Hold shift + click to select a range
8e58d9b
enh: add documentation for snap-in build config
navneel99 44afbd9
update
navneel99 e9def0e
Apply suggestions from code review
navneel99 039e1f4
rename page and add to sidebar
navneel99 a0a9e42
Merge branch 'main' into nav/ISS-84458
navneel99 f663762
update links
navneel99 fcdc515
Merge branch 'nav/ISS-84458' of github.com:devrev/fern-api-docs into …
navneel99 003703e
fix link
starlightknown e41010f
Update build-config.mdx
starlightknown 71fda0a
Update manifest.mdx
starlightknown e110300
Update manifest.mdx
starlightknown 99511f9
Update fern/docs/pages/references/manifest.mdx
starlightknown 75af020
Update fern/docs/pages/references/build-config.mdx
starlightknown 7f0a08b
Update build-config.mdx
starlightknown a4a0f87
Merge branch 'main' into nav/ISS-84458
starlightknown dd89f0b
Merge branch 'main' into nav/ISS-84458
Atul-Butola File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,61 @@ | ||||||
The build configuration is used to configure the build process of the snap-in. For example, it can be used to set the environment variables used during the build process. | ||||||
|
||||||
This is useful if the developer wants to import libraries from a different registry or wants to use private packages that | ||||||
requires an authentication token. | ||||||
starlightknown marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
## Specifying the Config | ||||||
|
||||||
Build config is defined as: | ||||||
|
||||||
```yaml | ||||||
build_config: | ||||||
environment_variables: | ||||||
- name: <Name of the environment variable> | ||||||
description: <Description of what the environment variable does> | ||||||
type: <Whether the value is a `constant` or in a developer `keyring`> | ||||||
value: <variable value or developer keyring name> | ||||||
``` | ||||||
|
||||||
For example, to import a library that uses the GitHub NPM registry, add | ||||||
the following variables to the build config | ||||||
|
||||||
```yaml | ||||||
build_config: | ||||||
environment_variables: | ||||||
- name: REGISTRY_NAME | ||||||
description: Name of the GitHub registry to import the library. | ||||||
type: constant | ||||||
value: npm.pkg.github.com | ||||||
- name: AUTH_TOKEN | ||||||
description: Token to access the registry | ||||||
type: keyring | ||||||
value: access_token | ||||||
``` | ||||||
|
||||||
Since "AUTH_TOKEN" is sensitive information that should not be hardcoded in the manifest, | ||||||
the developer can instead mention the name of the developer keyring and during snap-in version creation | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
and during? |
||||||
time, provide the developer keyring to take the value from. | ||||||
|
||||||
```yaml | ||||||
developer_keyrings: | ||||||
- name: access_token | ||||||
description: Access token for the GitHub registry | ||||||
display_name: Access Token | ||||||
``` | ||||||
|
||||||
## Using the variables defined in config | ||||||
|
||||||
If the package is present in private registries, the developer can update the `.npmrc` file in the `code` folder from the template to include the URL of the registry and the token. | ||||||
|
||||||
For example, to use variables defined in the manifest defined in the previous section, the `.npmrc` file will look something like this: | ||||||
|
||||||
```.npmrc | ||||||
@githubReg:registry=https://${REGISTRY_NAME} | ||||||
//${REGISTRY_NAME}/:_authToken=${AUTH_TOKEN} | ||||||
``` | ||||||
|
||||||
To ensure that the `.npmrc` file is valid and can be used to install the libraries, export the variables defined in the manifest locally with the correct values and install the library | ||||||
|
||||||
``` | ||||||
npm install @githubReg/<YOUR_LIBRARY> | ||||||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,7 @@ | ||
<Callout intent="note"> | ||
The following section is for version 2 of the manifest specification. For the previous version, see [Manifest V1](/snap-in-development/references/snap-in-v-1-manifest). | ||
The following section is for version 2 of the manifest specification. For the | ||
previous version, see [Manifest | ||
V1](/snap-in-development/references/snap-in-v-1-manifest). | ||
</Callout> | ||
|
||
The snap-in manifest is what the developers write to define a snap-in. The manifest has the following sections: | ||
|
@@ -14,7 +16,7 @@ version: 2 | |
|
||
## Keyrings | ||
|
||
Keyrings are secret tokens used to make calls to external systems. They can be categorized either as organization scoped or user scoped. Keyrings are specified in the manifest with the following syntax: | ||
Keyrings are secret tokens used to make calls to external systems. They can be categorized either as organization-scoped or user-scoped. Keyrings are specified in the manifest with the following syntax: | ||
|
||
```yaml | ||
keyrings: | ||
|
@@ -57,11 +59,12 @@ keyrings: | |
- snap_in_secret | ||
display_name: Your secret token | ||
``` | ||
|
||
Keyrings defined in the manifest can be provided in the snap-in configuration screens and are made available to the function. The keyring type is used to determine the type of the keyring and restricts selection on the configuration screen to valid types. | ||
|
||
Organization keyrings are common to the organization, while user keyrings are set per user. User keyrings are optional, so the developer must correctly handle cases where the keyring isn't found. | ||
|
||
To view the supported connection types, see [Keyrings](/snap-in-development/references/keyrings). | ||
To view the supported connection types, see [Keyrings](/references/keyrings). | ||
|
||
## Developer keyrings | ||
|
||
|
@@ -654,7 +657,7 @@ event_sources: | |
|
||
## Inputs | ||
|
||
Inputs are implemented using per-object schemas, which is a customization technique to store custom schemas inline with the object. Each input's schema maps to a FieldDescriptor. Inputs, like keyrings and event sources, are organization and user scoped. Organization-scoped inputs are set by the admins of the organization and are common across all users. User inputs are set individually. | ||
Inputs are implemented using per-object schemas, which is a customization technique to store custom schemas in line with the object. Each input's schema maps to a FieldDescriptor. Inputs, like keyrings and event sources, are organization and user-scoped. Organization-scoped inputs are set by the admins of the organization and are common across all users. User inputs are set individually. | ||
starlightknown marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Inputs are defined as: | ||
|
||
|
@@ -679,7 +682,8 @@ inputs: | |
ui: | ||
display_name: <Input field display name.> | ||
``` | ||
Inputs of type `timestamp`, `date` and `array` of `booleans` aren't supported. | ||
|
||
Inputs of type `timestamp`, `date`, and `array` of `booleans` aren't supported. | ||
|
||
## Tags | ||
|
||
|
@@ -690,7 +694,7 @@ For example: | |
```yaml | ||
tags: | ||
- name: github.branch.name | ||
description: Tag storing github branch name. | ||
description: Tag storing GitHub branch name. | ||
``` | ||
|
||
## Commands | ||
|
@@ -706,7 +710,7 @@ commands: | |
- surface: discussions | ||
object_types: | ||
- conversation | ||
usage_hint: "number of tokens to generate" | ||
usage_hint: 'number of tokens to generate' | ||
function: generate_summary | ||
``` | ||
|
||
|
@@ -743,3 +747,26 @@ automations: | |
``` | ||
|
||
For custom event sources, whatever event key you emit from your policy, the event name will be `custom:<your event key>`. | ||
|
||
## Build config | ||
|
||
The build configuration is used to configure the build process of the snap-in. For example, it can be used to set the environment variables used during the build process. This is useful if the snap-in requires libraries that | ||
are either private or from a different npm registry than the default. | ||
|
||
Build config is defined as: | ||
|
||
```yaml | ||
build_config: | ||
environment_variables: | ||
- name: <Name of the environment variable> | ||
description: <Description of what the environment variable does> | ||
type: <Whether the value is a constant or in a developer keyring> | ||
value: <variable value or developer keyring name> | ||
``` | ||
|
||
`type` can either be `constant` or `keyring`. | ||
|
||
`value` is either the actual value of the environment variable or name of the developer keyring that | ||
contains the secret depending on the type being `constant` or `keyring`. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we also link to the documentation page for build_configuration? |
||
|
||
For further information, see [Build Config](/references/build-config). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The definition is tautological: build configuration configures builds. The intro paragraph should have comprehensive statements, not an example. What else does it do besides set environment variables? I don't see anything else covered in this doc.