Added github PAT docs

Author: akclace

content/docs/Actions/index.md

@@ -26,10 +26,8 @@ def run(dry_run, args):
        return ace.result("Validation failed", param_errors={"dir": "relative paths not supported"})
 
    cmd_args = ["-Lla" if args.detail else "-La", args.dir]
-   out = exec.run("ls", cmd_args)
-   if out.error:
-       return ace.result(out.error)
-   return ace.result("File listing for " + args.dir, out.value)
+   out = exec.run("ls", cmd_args).value
+   return ace.result("File listing for " + args.dir, out)
 
 app = ace.app("List Files",
    actions=[ace.action("List Files", "/", run, description="Show the ls -a output for specified directory")],

content/docs/App/Overview.md

@@ -28,10 +28,8 @@ To create an app with a custom HTML page which shows a listing of files in your
 load("exec.in", "exec")
 
 def handler(req):
-   ret = exec.run("ls", ["-l", "/"])
-   if ret.error:
-       return {"Error": ret.error, "Lines": []}
-   return {"Error": "", "Lines": ret.value}
+   ret = exec.run("ls", ["-l", "/"]).value
+   return {"Error": "", "Lines": ret}
 
 app = ace.app("hello4",
               custom_layout=True,

content/docs/Configuration/Secrets.md

@@ -8,7 +8,7 @@ Clace supports secret management when working with apps. Secrets can be passed t
 
 ## Supported Providers
 
-Clace currently supports AWS Secrets Manager (ASM) and HashiCorp Vault as providers for secrets management. Secrets can also be read from the environment of the Clace server, which can be used in development and testing.
+Clace currently supports AWS Secrets Manager (ASM) and HashiCorp Vault as providers for secrets management. Secrets can also be read from the environment of the Clace server, which can be used in development and testing. Secrets can also be read from a local properties file.
 
 ## AWS Secrets Manager
 

content/docs/Configuration/Security.md

@@ -72,24 +72,44 @@ See [appsecurity]({{< ref "appsecurity" >}}) for details about the application l
 
 ## Private Repository Access
 
-The `app create` and `app reload` commands can read public GitHub repositories. If the repository is private, to be able to access the repo, the [ssh key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) needs to be specified. In the `clace.toml` config file, create an entry like:
+The `app create` and `app reload` commands can read public GitHub repositories. If the repository is private, to be able to access the repo, the [ssh key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account) or [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) needs to be specified.
+
+### SSH Keys
+
+For SSH key, in the `clace.toml` config file, create an entry like:
 
 ```toml {filename="clace.toml"}
 [git_auth.mykey]
-key_file_path = "/Users/myuser/.ssh/infoclace_rsa"
-password = ""
+key_file_path = "/Users/myuser/.ssh/id_rsa"
+password = "mypassphrase"
 ```
 
-`mykey` is the git auth key name, `key_file_path` points to the location of a private key file for a user with access to the repository. When running `app create`, add the `--git-auth mykey` option and use the git url instead of http url (like `git@github.com:claceio/clace.git/examples/disk_usage`). The private key specified will be used for accessing the repository. `app reload` command will automatically use the same key as specified during the create. To set the default git key to use, add in config:
+`mykey` is the git auth key name, `key_file_path` points to the location of a private key file for a user with access to the repository and `password` is the passphrase if any for the file.
+
+{{<callout type="info" >}}
+Use `ssh-keygen -l -f ~/.ssh/id_rsa.pub` (on public key) to check if the fingerprint matches the SHA256 fingerprint shown at https://github.com/settings/keys. To verify the passphrase, use `ssh-keygen -y -f ~/.ssh/id_rsa` (on the private key) and type in the passphrase to check if the passphrase is correct.
+{{</callout>}}
+
+### Personal Access Token
+
+For personal access token, set
+
+```toml {filename="clace.toml"}
+[git_auth.mypat]
+user_id = "myid"
+password = "github_pat_11A7FXXXXXXX"
+```
+
+The `user_id` needs to be set to an non-empty value like the github id even though it is ignored for the auth.
+
+When running `app create`, add `--git-auth mykey` or `--git-auth mypat` option. The private key specified will be used for accessing the repository. `app reload` command will automatically use the same key as specified during the create. To set the default git key to use, add in config:
 
 ```toml {filename="clace.toml"}
 [security]
 default_git_auth = "mykey"
 ```
 
-If an app has no `git_auth` set and uses a repo with git url (starts with `git@github.com:`), then the default_git_auth will be used if it is specified in the config. This git key is used for `apply` files also.
-
-To change the git auth key for an app, run:
+This git key is used for `apply` and `sync` also. To change the git auth key for an app, run:
 
 ```bash
 clace app update-settings git-auth newkey /myapp

content/docs/Plugins/Catalog.md

@@ -45,6 +45,8 @@ All the API's support the following parameters:
 - **form_encoding** (string, optional) : the form encoding to use, `application/x-www-form-urlencoded` (default) or `multipart/form-data`
 - **json_body** (object, optional) : the object to send as json encoded body
 - **auth_basic** (tuple(string, string), optional): HTTP basic auth username and password
+- **auth_signature** (string, optional): Signature auth type
+- **error_on_fail** (bool, optional): Whether to fail on non-2xx status code, default true
 
 The response for all API's (`value` within `plugin_response`) contains following properties:
 
@@ -55,15 +57,10 @@ The response for all API's (`value` within `plugin_response`) contains following
 - **body()** (string) : the response body as a string
 - **json()** (object) : the response body un-marshalled as a json
 
-If the API calls fails to go through then the plugin response `error` property will be set. If the API goes through, then the response `error` will not be set, even if API call fails with an HTTP error. The `status_code` will indicate whether the API succeeded on the server. To handle all possible error conditions, do (change to handle all 2xx codes if required)
+If the API calls fails to go through then the plugin response `error` property will be set. If the API returns non 2xx status code, error is set (unless `error_on_fail` is False). The `status_code` will indicate whether the API succeeded on the server. To make an API call and parse the response as JSON, do
 
 ```python {filename="app.star"}
-ret = http.get("http://localhost:9999/test")
-if ret.error or ret.value.status_code != 200:
-    return # error handling
-
-val = ret.value.json()
-# success handling
+ret = http.get("http://localhost:9999/test").value.json()
 ```
 
 ## Exec Plugin

content/docs/QuickStart.md

@@ -91,10 +91,8 @@ The app defines a run handler which runs `ls` on the specified directory. The ou
 load ("exec.in", "exec")
 
 def run(dry_run, args):
-   out = exec.run("ls", ["-Lla"])
-   if out.error:
-       return ace.result(out.error)
-   return ace.result("File listing for " + args.dir, out.value)
+   out = exec.run("ls", ["-Lla"]).value
+   return ace.result("File listing for " + args.dir, out)
 
 app = ace.app("List Files",
    actions=[ace.action("List Files", "/", run, description="Show the ls -a output for specified directory")],