refactor: update dagger module docs (#150)

* docs: update option docs

* fix: add trailing slash for service endpoints

* docs: add how to use to README.md

README.md

@@ -30,7 +30,126 @@ Once you have these tools, you are ready to install and use `gale`.
 
 ## How to Use
 
-Coming Soon!
+### Setup Dagger Module
+
+To avoid adding `-m github.com/aweris/gale/daggerverse/gale` to every command, you can add run the following command to
+set `DAGGER_MODULE` environment variable:
+
+```shell
+export DAGGER_MODULE=github.com/aweris/gale/daggerverse/gale
+```
+
+### Listing a Workflows
+
+To get a list of workflows, you can use the dagger call workflows list command.
+
+Below is the help output showing the usage and options:
+
+```shell
+ Usage:
+ dagger call workflows list [flags]
+
+ Aliases:
+ list, List
+
+ Flags:
+ --branch string Git branch to checkout. Used with --repo. If tag and branch are both specified, tag takes precedence.
+ -h, --help help for list
+ --repo string Name of the repository. Format: owner/name.
+ --source Directory Directory containing the repository source. Has precedence over repo.
+ --tag string Git tag to checkout. Used with --repo. If tag and branch are both specified, tag takes precedence.
+ --workflows-dir string Path to the workflow directory. (default ".github/workflows")
+```
+
+#### Examples
+
+List all workflows for current repository:
+
+```shell
+dagger call workflows list --source "."
+```
+
+List workflows for a specific repository and directory:
+
+```shell
+dagger call workflows list --repo aweris/gale --branch main --workflows-dir ci/workflows
+```
+
+### Run a Workflow
+
+For running workflows, you'll mainly use `dagger [call|download] workflows run [flags] [sub-command]`. Below is
+the help output showing the usage and options:
+
+```shell
+ Usage:
+ dagger call workflows run [flags]
+ dagger call workflows run [command]
+
+ Aliases:
+ run, Run
+
+ Available Commands:
+ config Configuration for the workflow run.
+ directory Directory returns the directory of the workflow run information.
+ result Result returns executes the workflow run and returns the result.
+
+ Flags:
+ --branch string Git branch to checkout. Used with --repo. If tag and branch are both specified, tag takes precedence.
+ --event string Name of the event that triggered the workflow. (default "push")
+ --event-file File The file with the complete webhook json event payload.
+ -h, --help help for run
+ --job string Name of the job to run. If empty, all jobs will be run.
+ --repo string Name of the repository. Format: owner/name.
+ --runner-debug Enables debug mode.
+ --runner-image string Docker image to use for the runner. (default "ghcr.io/dagger/gale:latest")
+ --source Directory Directory containing the repository source. Has precedence over repo.
+ --tag string Git tag to checkout. Used with --repo. If tag and branch are both specified, tag takes precedence.
+ --token Secret GitHub token to use for authentication.
+ --workflow string Name of the workflow to run.
+```
+
+#### Sub-Commands
+
+- **result**: Returns the summary of the workflow run.
+
+```shell
+dagger call workflow run ... --workflow build results
+```
+
+- **directory**: Exports workflow run data.
+
+The help output for directory option
+```shell
+Usage:
+ dagger download workflows run directory [flags]
+
+Aliases:
+ directory, Directory
+
+Flags:
+ -h, --help help for directory
+ --include-artifacts Adds the uploaded artifacts to the exported directory.
+ --include-event Adds the event file to the exported directory.
+ --include-repo Adds the repository source to the exported directory.
+ --include-secrets Adds the mounted secrets to the exported directory.
+```
+
+Example command for exporting the workflow run data:
+```shell
+dagger download workflow run ... --workflow build directory --export-path .gale/exports --include-artifacts
+```
+
+##### Examples
+
+Running a workflow for remote repository and downloading exporting the workflow run data and artifacts:
+
+```shell
+ dagger download --focus=false workflows run --repo kubernetes/minikube --branch master --workflow build --job build_minikube --token $GITHUB_TOKEN directory --export-path .gale/exports --include-artifacts
+```
+
+**Notes for Above Example:**
+- `--focus=false` is used to disable focus mode. Required for displaying the execution logs.
+- `--token` is optional however it is required for the workflow in this example.
 
 ## Feedback and Collaboration
 

daggerverse/gale/opts.go

@@ -5,34 +5,34 @@ package main
 // This is copy of RepoOpts from daggerverse/gale/repo.go to be able to expose options with gale module and pass them to
 // the repo module just type casting.
 type RepoOpts struct {
- Source *Directory `doc:"The directory containing the repository source. If source is provided, rest of the options are ignored."`
- Repo string `doc:"The name of the repository. Format: owner/name."`
- Branch string `doc:"Branch name to checkout. Only one of branch or tag can be used. Precedence is as follows: tag, branch."`
- Tag string `doc:"Tag name to checkout. Only one of branch or tag can be used. Precedence is as follows: tag, branch."`
+ Source *Directory `doc:"Directory containing the repository source. Has precedence over repo."`
+ Repo string `doc:"Name of the repository. Format: owner/name."`
+ Branch string `doc:"Git branch to checkout. Used with --repo. If tag and branch are both specified, tag takes precedence."`
+ Tag string `doc:"Git tag to checkout. Used with --repo. If tag and branch are both specified, tag takes precedence."`
 }
 
 // WorkflowsDirOpts represents the options for getting workflow information.
 type WorkflowsDirOpts struct {
- WorkflowsDir string `doc:"The relative path to the workflow directory." default:".github/workflows"`
+ WorkflowsDir string `doc:"Path to the workflow directory." default:".github/workflows"`
 }
 
 // WorkflowsRunOpts represents the options for running a workflow.
 type WorkflowsRunOpts struct {
- Workflow string `doc:"The workflow to run." required:"true"`
- Job string `doc:"The job name to run. If empty, all jobs will be run."`
- Event string `doc:"Name of the event that triggered the workflow. e.g. push" default:"push"`
- EventFile *File `doc:"The file with the complete webhook event payload."`
- RunnerImage string `doc:"The image to use for the runner." default:"ghcr.io/catthehacker/ubuntu:act-latest"`
- RunnerDebug bool `doc:"Enable debug mode." default:"false"`
- Token *Secret `doc:"The GitHub token to use for authentication."`
+ Workflow string `doc:"Name of the workflow to run."`
+ Job string `doc:"Name of the job to run. If empty, all jobs will be run."`
+ Event string `doc:"Name of the event that triggered the workflow." default:"push"`
+ EventFile *File `doc:"The file with the complete webhook json event payload."`
+ RunnerImage string `doc:"Docker image to use for the runner." default:"ghcr.io/catthehacker/ubuntu:act-latest"`
+ RunnerDebug bool `doc:"Enables debug mode." default:"false"`
+ Token *Secret `doc:"GitHub token to use for authentication."`
 }
 
 // WorkflowRunDirectoryOpts represents the options for exporting a workflow run.
 type WorkflowRunDirectoryOpts struct {
- IncludeRepo bool `doc:"Include the repository source in the exported directory." default:"false"`
- IncludeSecrets bool `doc:"Include the secrets in the exported directory." default:"false"`
- IncludeEvent bool `doc:"Include the event file in the exported directory." default:"false"`
- IncludeArtifacts bool `doc:"Include the artifacts in the exported directory." default:"false"`
+ IncludeRepo bool `doc:"Adds the repository source to the exported directory." default:"false"`
+ IncludeSecrets bool `doc:"Adds the mounted secrets to the exported directory." default:"false"`
+ IncludeEvent bool `doc:"Adds the event file to the exported directory." default:"false"`
+ IncludeArtifacts bool `doc:"Adds the uploaded artifacts to the exported directory." default:"false"`
 }
 
 // FIXME: add jobs to WorkflowRunReport when dagger supports map type

daggerverse/source/source.go

@@ -152,6 +152,10 @@ func (m *ArtifactServiceSource) BindAsService(ctx context.Context, container *Co
  return nil, err
  }
 
+ // normalise the endpoint to remove the trailing slash -- dagger returns the endpoint without the trailing slash
+ // but the github actions expects the endpoint with the trailing slash
+ endpoint = endpoint + "/"
+
  return container.
  WithServiceBinding("artifact-service", service).
  WithEnvVariable("ACTIONS_RUNTIME_URL", endpoint).
@@ -222,6 +226,10 @@ func (m *ArtifactCacheServiceSource) BindAsService(ctx context.Context, containe
  return nil, err
  }
 
+ // normalise the endpoint to remove the trailing slash -- dagger returns the endpoint without the trailing slash
+ // but the github actions expects the endpoint with the trailing slash
+ endpoint = endpoint + "/"
+
  return container.
  WithServiceBinding("artifact-cache-service", service).
  WithEnvVariable("ACTIONS_CACHE_URL", endpoint).