Skip to content

Commit f6b46fa

Browse files
spbsolublespbsoluble
committed
chore(docs): Update README.md with v4 info and examples
1 parent 79bd7a4 commit f6b46fa

File tree

1 file changed

+126
-22
lines changed

1 file changed

+126
-22
lines changed

‎README.md‎

Lines changed: 126 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,40 +1,144 @@
1-
### 👨🏿‍🚀 Actions v3 Workflows
1+
### 👨🏿‍🚀 Actions v4 Workflows
22

3-
### What's new in v3
4-
* The v3 Actions make use of [doctool](https://github.com/Keyfactor/doctool)
5-
* Polaris SAST/SCA scans run on push to release and main branches
6-
* All actions are being migrated to forks in the keyfactor org for security hardening purposes. AB#55122
7-
* Access to 3rd party actions will be restrcited in the keyfactor org
8-
* The keyfactor-action-staging organization can be used for developing workflows that will need to be transferred to the keyfactor org before making it public
9-
* Post-release workflow added: Auto-create PR from release branch to main
10-
* Additional jobs/actions may be added to the kf-post-release.yml workflow in this repository (.github/workflows folder)
3+
### What's new in v4
4+
* The v4 Actions make use of [doctool](https://github.com/Keyfactor/doctool) to take Command screenshots for Universal Orchestrator extension store-type creation.
115

12-
These workflows are designed to work with the latest [keyfactor-bootstrap-workflow.yml "Keyfactor Bootstrap v3 Workflow"](https://github.com/Keyfactor/.github/blob/main/workflow-templates/keyfactor-bootstrap-workflow-v3.yml)
6+
### Usage
137

14-
### 🚀The Bootstrap workflow for v3 Actions perform the following steps:
8+
#### Prerequisites
9+
- Ensure an `integration-manifest.json` file is present in the root of your repository. For the schema, see the v2 [integration-manifest-schema.json](https://keyfactor.github.io/v2/integration-manifest-schema.json)
10+
11+
#### Example `integration-manifest.json`
12+
```json
13+
{
14+
"$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json",
15+
"integration_type": "anyca-plugin",
16+
"name": "Example AnyCA REST Gateway Plugin",
17+
"status": "pilot",
18+
"support_level": "kf-supported",
19+
"link_github": true,
20+
"update_catalog": true,
21+
"description": "Example Plugin for the AnyCA REST Gateway framework",
22+
"gateway_framework": "25.0.0",
23+
"release_dir": "example-caplugin\\bin\\Release",
24+
"release_project": "example-caplugin\\example_extension.csproj",
25+
"about": {
26+
"carest": {
27+
"ca_plugin_config": [
28+
{
29+
"name": "ApiKey",
30+
"description": "The API Key for the The CA API"
31+
},
32+
{
33+
"name": "Username",
34+
"description": "Username for the CA API service account"
35+
},
36+
{
37+
"name": "Password",
38+
"description": "Password for the CA API service account"
39+
},
40+
{
41+
"name": "BaseUrl",
42+
"description": "The Base URL for the CA API"
43+
},
44+
{
45+
"name": "Enabled",
46+
"description": "Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available."
47+
}
48+
],
49+
"enrollment_config": [
50+
{
51+
"name": "CertificateValidityInYears",
52+
"description": "Number of years the certificate will be valid for"
53+
},
54+
{
55+
"name": "Email",
56+
"description": "Email address of the requestor"
57+
},
58+
{
59+
"name": "OrganizationName",
60+
"description": "Name of the organization to be validated against"
61+
}
62+
],
63+
"product_ids": [
64+
"ExampleProductSslOvBasic",
65+
"ExampleProductSslEvBasic",
66+
"ExampleProductSslDvGeotrust",
67+
"ExampleProductSslDvThawte",
68+
"ExampleProductSslOvThawteWebserver",
69+
"ExampleProductSslEvThawteWebserver",
70+
"ExampleProductSslOvGeotrustTruebizid",
71+
"ExampleProductSslEvGeotrustTruebizid",
72+
"ExampleProductSslOvSecuresite",
73+
"ExampleProductSslEvSecuresite",
74+
"ExampleProductSslOvSecuresitePro",
75+
"ExampleProductSslEvSecuresitePro"
76+
]
77+
}
78+
}
79+
}
80+
```
81+
82+
#### Example workflow `keyfactor-bootsrap-workflow.yml`
83+
```yaml
84+
name: Keyfactor Bootstrap Workflow
85+
86+
on:
87+
workflow_dispatch:
88+
pull_request:
89+
types: [opened, closed, synchronize, edited, reopened]
90+
push:
91+
create:
92+
branches:
93+
- 'release-*.*'
94+
95+
jobs:
96+
call-starter-workflow:
97+
uses: keyfactor/actions/.github/workflows/starter.yml@v4
98+
with:
99+
command_token_url: ${{ vars.COMMAND_TOKEN_URL }} # Only required for doctool generated screenshots
100+
command_hostname: ${{ vars.COMMAND_HOSTNAME }} # Only required for doctool generated screenshots
101+
command_base_api_path: ${{ vars.COMMAND_API_PATH }} # Only required for doctool generated screenshots
102+
secrets:
103+
token: ${{ secrets.V2BUILDTOKEN}} # REQUIRED
104+
gpg_key: ${{ secrets.KF_GPG_PRIVATE_KEY }} # Only required for golang builds
105+
gpg_pass: ${{ secrets.KF_GPG_PASSPHRASE }} # Only required for golang builds
106+
scan_token: ${{ secrets.SAST_TOKEN }} # REQUIRED
107+
entra_username: ${{ secrets.DOCTOOL_ENTRA_USERNAME }} # Only required for doctool generated screenshots
108+
entra_password: ${{ secrets.DOCTOOL_ENTRA_PASSWD }} # Only required for doctool generated screenshots
109+
command_client_id: ${{ secrets.COMMAND_CLIENT_ID }} # Only required for doctool generated screenshots
110+
command_client_secret: ${{ secrets.COMMAND_CLIENT_SECRET }} # Only required for doctool generated screenshots
111+
```
112+
113+
### 🚀The Bootstrap workflow for v4 Actions perform the following steps:
15114
16115
* Checkout integration repository
17-
* Get values from integration-manifest.json [***assign-env-from-json***]
116+
* Call [starter.yml](.github/workflows/starter.yml) workflow
117+
* Get values from integration-manifest.json [assign-env-from-json](.github/workflows/assign-env-from-json.yml)
18118
* Discover primary programming language from the repository [***action-get-primary-language***]
19-
* Determine event_name: create, push, pull_request, workflow_dispatch [***github-release]***
20-
* Run the workflows and conditionalized steps to produce a build. If conditions match, release artifacts are delivered [***dotnet-build-and-release | go-build-and-release***]
119+
* Determine event_name: `create, push, pull_request, workflow_dispatch` [github-release.yml](.github/workflows/github-release.yml)
120+
* Run the workflows and conditionalized steps to produce a build. If conditions match, release artifacts are delivered
121+
[dotnet-build-and-release.yml](.github/workflows/dotnet-build-and-release.yml) or [go-build-and-release.yml](.github/workflows/go-build-and-release.yml)
122+
workflow will be run depending on the `detected-primary-language` step in [starter.yml](.github/workflows/starter.yml)
21123

22124
#### On Create:
23125
* Configure repository settings - This will use the properties from the json to update topic and description, and will set the teams permissions on the repo accordingly. If the ref created is a branch that matches "release-\*.\*", branch protection is added, autlink reference set ab# to devops [***kf-configure-repo***]
24126

25127
#### On push or workflow_dispatch:
26128
* Just run the build on the branch with the commit without producing release artifacts
27-
* * C#: run the dotnet-build-and-release.yml workflow
129+
* * C#: run the [dotnet-build-and-release.yml](.github/workflows/dotnet-build-and-release.yml) workflow
28130
* * Go builds: run the go-build-and-release.yml workflow (still in progress)
29-
* All languages: Generate a readme using doctool and (conditionally) a catalog entry [***generate-readme, update-catalog***]
131+
* All languages:
132+
* * Generate/Update `README.md` using `doctool` [generate-readme.yml](.github/workflows/generate-readme.yml)
133+
* * (conditionally) a catalog entry [update-catalog](.github/workflows/update-catalog.yml) will be created/updated if the json manifest has `"update_catalog": true` in the `integration-manifest.json` file
30134

31135
#### On pull_request[opened, closed, synchronize, edited, reopened]:
32-
[***dotnet-build-and-release | go-build-and-release***]
33-
* If the pr destination is a release-*.* branch, set flags to produce release artifacts
34-
* If the pr is determined to be open or merged but not closed (synchronize), a prerelease artifact will be uploaded
35-
* If the pr is determined to be merged and closed, a final release is built
36-
* Polaris SAST/SCAN scans run when push to release-* or main occurs
37-
* If PR to release branch is merged/closed, a new PR will be automatically generated. This will need to be approved manually and **should not** be approved for hotfix branches
136+
[dotnet-build-and-release.yml](.github/workflows/dotnet-build-and-release.yml) workflow or [go-build-and-release.yml](.github/workflows/go-build-and-release.yml) workflow will be run depending on the detected primary language
137+
* If the pr destination is a `release-*.*` branch, set flags to produce release artifacts
138+
* If the pr is determined to be `open` or `merged` but not `closed` (synchronize), a prerelease artifact will be uploaded
139+
* If the pr is determined to be `merged` and `closed`, a final "official" release is built and published to GitHub releases, and if `"update_catalog": true` is set in the json manifest, a catalog entry will be created/updated
140+
* Polaris SAST/SCAN scans run when push to `release-*` or main occurs
141+
* If PR to release branch is `merged/closed`, a new PR will be automatically generated. This will need to be approved manually and **should not** be approved for hotfix branches
38142

39143

40144

0 commit comments

Comments
 (0)