updates documentation

README.md

@@ -1,67 +1,70 @@
-# submit-signing-request
+# SignPath Github Actions
 
-This Submit Signing Request action allowing you to sign the build artifact using SignPath signing services.
+This repository contains the Github Actions that can be used to submit a signing request to [SignPath.io](https://about.signpath.io).
 
-## Usage
+> [!WARNING]
+> These actions are currently in development and only available in preview mode for selected customers. Contact [support@signpath.io](mailto:support@signpath.io) if you are interested in using them.
 
-See [action.yml](action.yml)
+Currently, there is only one action available, `submit-signing-request`.
 
-### Sign published artifact and download the signed artifact back to the build agent file system
+## submit-signing-request
+
+This action allows you to sign the build artifact using SignPath signing services.
+
+See [action.yml](actions/submit-signing-request/action.yml)
+
+### Prerequisites
+
+* The Github Actions Trusted Build System must be enabled in the organization and linked to the respective project.
+* The artifact must be uploaded to the Github Actions workflow using the [actions/upload-artifact](https://github.com/actions/upload-artifact) action before it can be signed. 
+* The `secrets.SIGNPATH_API_TOKEN` variable must belong to a user who has a submitter role in the referenced signing policy
+
+### Samples
+
+#### Sign published artifact and download the signed artifact back to the build agent file system
 
 ```yaml
 steps:
 - id: optional_step_id
   uses: signpath/github-actions/actions/submit-signing-request@v0.1
       with:
-        connector-url: '<SignPath GitHub Actions connector URL>'
         api-token: '${{ secrets.SIGNPATH_API_TOKEN }}'
-        organization-id: '<SignPath Organization Id>'
-        project-slug: '<SignPath Project Slug>'
-        signing-policy-slug: '<SignPath Policy Slug>'
-        artifact-configuration-slug: '<SignPath Artifact Configuration Slug>'
-        artifact-name: '<Name of the artifact to sign>'
+        organization-id: '<SignPath organization id>'
+        project-slug: '<SignPath project slug>'
+        signing-policy-slug: '<SignPath signing policy slug>'
+        artifact-configuration-slug: '<SignPath artifact configuration slug>'
+        artifact-name: '<Name of the Github Actions artifact>'
         github-token: '${{ secrets.GITHUB_TOKEN }}'
         signed-artifact-destination-path: '<Destination path for the signed artifact>'
 ```
 
-### Sign published artifact and continue workflow execution
+#### Sign published artifact and continue workflow execution (do not download the signed artifact)
 
 ```yaml
 steps:
 - id: optional_step_id
   uses: signpath/github-actions/actions/submit-signing-request@v0.1
       with:
-        connector-url: '<SignPath GitHub Actions connector URL>'
         api-token: '${{ secrets.SIGNPATH_API_TOKEN }}'
-        organization-id: '<SignPath Organization Id>'
-        project-slug: '<SignPath Project Slug>'
-        signing-policy-slug: '<SignPath Policy Slug>'
-        artifact-configuration-slug: '<SignPath Artifact Configuration Slug>'
+        organization-id: '<SignPath organization id>'
+        project-slug: '<SignPath project slug>'
+        signing-policy-slug: '<SignPath policy slug>'
+        artifact-configuration-slug: '<SignPath artifact configuration slug>'
         artifact-name: '<Name of the artifact to sign>'
         github-token: '${{ secrets.GITHUB_TOKEN }}'
 ```
 
-### Sign published artifact action output parameters
-submit-signing-request supports the following output parameters:
-- signing-request-id - The id of the newly created signing request
-- signing-request-web-url - The url of the signing request in SignPath
-- signpath-api-url - The base API url of the SignPath API
-- signed-artifact-download-url - The url of the signed artifact in SignPath
+#### Use output parameters
+
+The `submit-signing-request` action supports the following output parameters:
+- `signing-request-id`: The id of the newly created signing request
+- `signing-request-web-url`: The url of the signing request in SignPath
+- `signpath-api-url`: The base API url of the SignPath API
+- `signed-artifact-download-url`: The url of the signed artifact in SignPath
 
 You can use the output parameters in the following way:
 ```yaml
     steps:
     - name: Print the signing request id
-      run:  echo "Output [${{steps.submit_signing_request_step_id.outputs.signing-request-id }}]"
-```
-
-### SignPath API token
-Please make sure the API token has the following permissions:
-- Reader for the specified SignPath project
-- Submitter for the specified SignPath policy
-
-### Troubleshooting
-- N/A
-
-### Known issues
-- N/A
+      run:  echo "Output [${{steps.<submit_signing_request_step_id>.outputs.signing-request-id }}]"
+```

actions/submit-signing-request/action.yml

@@ -4,7 +4,7 @@ description: 'Submits signing request to SignPath and downloads the signed artif
 inputs:
   connector-url:
     description: 'GitHub Actions SignPath connector URL'
-    default: 'https://CONNECTOR_URL'
+    default: 'https://githubactions.connectors.signpath.io'
     required: true
   api-token:
     description: 'SignPath REST API access token. More details: https://about.signpath.io/documentation/build-system-integration#authentication'
@@ -19,10 +19,10 @@ inputs:
     description: 'SignPath signing policy slug'
     required: true
   artifact-configuration-slug:
-    description: 'SignPath artifact configuration'
+    description: 'SignPath artifact configuration slug'
     required: true
   artifact-name:
-    description: 'Name of the artifact to sign'
+    description: 'Name of the Github Actions artifact'
     required: true
   signed-artifact-destination-path:
     description: 'Path where the signed artifact will be saved, if empty then the task will not download the artifact from SignPath'