Skip to content

Update platform-services' worker documentation #198

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.

Sign up for GitHub

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

Merged
RemiBou merged 1 commit into from
Jun 16, 2025
Merged

Update platform-services' worker documentation #198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions jfrog-applications/jfrog-cli/cli-for-jfrog-platform-services/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,22 @@ This page describes how to use JFrog CLI with JFrog Platform Services.

Read more about JFrog CLI [here](https://jfrog-external.fluidtopics.net/r/help/JFrog-CLI/JFrog-CLI).

**Managing Workers**
**Managing JFrog Workers**

JFrog CLI allows you to fully manage your platform workers.
Workers is a JFrog Platform service that allows you to extend and control your execution flows. It provides a serverless execution environment. You can create workers to enhance the platform's functionality. Workers are triggered automatically by events within the JFrog Platform, giving you the flexibility to address specific use cases. For on-demand tasks, configure Http-triggered workers.

You can read more about JFrog Workers [here](https://jfrog.com/help/r/jfrog-platform-administration-documentation/workers).


With the JFrog CLI for JFrog Worker it is possible to:

- [Initialize a JFrog worker](./platform-workers-init.md)
- [Test-Run a JFrog worker](./platform-workers-dry-run.md)
- [Deploy a JFrog worker](./platform-workers-deploy.md)
- [Add secrets to a JFrog worker](./platform-workers-add-secret.md)
- [Undeploy a JFrog worker](./platform-workers-undeploy.md)
- [Trigger an HTTP-Triggered worker](./platform-workers-execute.md)
- [Retrieve the list of available events](./platform-workers-list-event.md)
- [Retrieve the list of existing JFrog workers](./platform-workers-list.md)
- [Retrieve a JFrog worker's execution history](./platform-workers-execution-history.md)
- [Edit an SCHEDULE_EVENT worker schedule](./platform-workers-edit-schedule.md)
18 changes: 11 additions & 7 deletions ...ations/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-add-secret.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,17 @@
# Add worker secret
# Add a secret to a worker manifest

## Overview

This command is used to edit a worker manifest to add secret that can be used for deployment or/and execution.
This command is used to edit a worker manifest in order to add or edit secret that can be used for deployment or/and execution.

| | |
Secrets are store encrypted with a master password that will be requested by the command.

Once secrets are added to the manifest the master password will be required by the `deploy` and `test-run` commands.

| | |
|------------------------|---------------------------------------------------------|
| Command name | worker add-secret |
| Abbreviation | worker as |
| Command name | worker add-secret |
| Abbreviation | worker as |
| **Command options:** | |
| `--edit` | \[Default: false] Whether to update an existing secret. |
| **Command arguments:** | |
Expand All @@ -18,5 +22,5 @@ This command is used to edit a worker manifest to add secret that can be used fo
Add a secret name `my-secret` to a worker initialized in the current directory.

```
jfrog worker add-secret my-secret
```
jf worker add-secret my-secret
```
16 changes: 8 additions & 8 deletions ...plications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-deploy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@

This command is used to update the worker definition (code, description , filter, secret ...) on your Artifactory instance.

| | |
| | |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker deploy |
| Abbreviation | worker d |
| **Command options:** | |
| `--server-id` | \[Optional] Server ID configured using the config command. |
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| `--no-secrets` | \[Default: false] Do not use registered secrets. |
| Command name | worker deploy |
| Abbreviation | worker d |
| **Command options:** | |
| `--server-id` | \[Optional] Server ID configured using the config command. |
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| `--no-secrets` | \[Default: false] Do not use registered secrets. |

## Example

Deploy a worker to server with id `my-server`.

```
jfrog worker server deploy --server-id my-server
jf worker server deploy --server-id my-server
```
27 changes: 14 additions & 13 deletions ...lications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-dry-run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,25 @@
# Test a worker
# Test Run a worker

## Overview

Dry run a worker. The worker needs to be initialized before running this command.
Test-run a worker. The worker needs to be initialized before running this command.
The command will execute the worker with its local content, so it can be used to test the worker execution before pushing the local changes to the server.

| | |
| | |
|------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker dry-run |
| Abbreviation | worker dr |
| **Command options:** | |
| `--server-id` | \[Optional] Server ID configured using the config command. |
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| `--no-secrets` | \[Default: false] Do not use registered secrets. |
| **Command arguments:** | |
| Command name | worker test-run |
| Abbreviation | worker dry-run, worker dr, worker tr |
| **Command options:** | |
| `--server-id` | \[Optional] Server ID configured using the config command.|
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| `--no-secrets` | \[Default: false] Do not use registered secrets. |
| **Command arguments:** | |
| json-payload | The json payload expected by the worker. Use `-` to read the payload from standard input. Use `@<file-path>` to read from a file located at <file-path>. |

## Example

Dry run a worker initialized in the current directory, with a payload located in a file named `payload.json` from the same directory.
Test-run a worker initialized in the current directory, with a payload located in a file named `payload.json` from the same directory.

```
jfrog worker dry-run @payload.json
```
jf worker dry-run @payload.json
```
24 changes: 24 additions & 0 deletions ...ons/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-edit-schedule.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@

# Edit a worker schedule

## Overview

Edit the manifest of a SCHEDULED_EVENT worker to udpate the schedule criteria.

The worker should be deploy afterward with `jf worker deploy` for the change to be applied to the server.

| | |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker edit-schedule |
| Abbreviation | worker es |
| **Command options:** | |
| `--cron` | \[Mandatory] A standard cron expression with minutes resolution. Seconds resolution is not supported by Worker service. |
| `--timezone` | \[Default: UTC] The timezone to use for scheduling. |

## Example

Edit a worker manifest so that it is executed every minute.

```
jf worker edit-schedule --cron "* * * * *"
```
29 changes: 23 additions & 6 deletions ...lications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execute.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,15 @@

Execute an HTTP-triggered worker.

| | |
| | |
|------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker execute |
| Abbreviation | worker exec, worker e |
| Command name | worker execute |
| Abbreviation | worker exec, worker e |
| **Command options:** | |
| `--server-id` | \[Optional] Server ID configured using the config command. |
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| **Command arguments:** | |
| `--server-id` | \[Optional] Server ID configured using the config command. |
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| `--project-key` | \[Optional] The key of the project that the worker belongs to.|
| **Command arguments:** | |
| worker-key | The worker key. If not provided it will be read from the `manifest.json` in the current directory. |
| json-payload | The json payload expected by the worker. Use `-` to read the payload from standard input. Use `@<file-path>` to read from a file located at <file-path>. |

Expand All @@ -23,3 +24,19 @@ Execute an HTTP-triggered worker initialized in the current directory, with a pa
jf worker execute @payload.json
```

Execute an HTTP-triggered worker with a payload from the standard input.

```
jf worker execute - <<EOF
{
“a”: “key”,
“an-integer”: 14
}
EOF
```

Execute an HTTP-triggered worker by providing the payload as an argument.

```
jf worker execute ‘{“my”:”payload”}’
```
26 changes: 26 additions & 0 deletions ...jfrog-cli/cli-for-jfrog-platform-services/platform-workers-execution-history.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@

# Show a worker execution history

## Overview

Display in a json format the execution history of a specific worker.

| | |
|------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker execution-history |
| Abbreviation | worker exec-hist, worker eh |
| **Command options:** | |
| `--server-id` | \[Optional] Server ID configured using the config command. |
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds. |
| `--project-key` | \[Optional] List events available to a specific project.|
| `--with-test-runs` | \[Default: false] Whether to include test-runs entries.|
| **Command arguments:** | |
| worker-key | \[Optional] The worker key. If not provided it will be read from the `manifest.json` in the current directory. |

## Example

Retrieves the execution history of a worker named `my-worker` including test runs.

```
jf worker execution-history --with-test-runs my-worker
```
41 changes: 27 additions & 14 deletions ...applications/jfrog-cli/cli-for-jfrog-platform-services/platform-workers-init.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,36 @@

## Overview

This command is used to initialize a new platform worker.

| | |
|------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker init |
| Abbreviation | worker i |
| **Command options:** | |
| `--force` | \[Default: false] Whether to overwrite existing files. |
| `--no-test` | \[Default: false] Whether to skip tests generation. |
| **Command arguments:** | |
| action | The action that will trigger the worker (BEFORE_DOWNLOAD, AFTER_DOWNLOAD, BEFORE_UPLOAD, AFTER_CREATE, AFTER_BUILD_INFO_SAVE, AFTER_MOVE, GENERIC_EVENT, BEFORE_CREATE_TOKEN, ...). |
| worker-name | The name of the worker |
This command is used to initialize a new JFrog worker.

| | |
|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Command name | worker init |
| Abbreviation | worker i |
| **Command options:** ||
| `--server-id` | \[Optional] Server ID configured using the config command.|
| `--timeout-ms` | \[Default: 5000] The request timeout in milliseconds.|
| `--force` | \[Default: false] Whether to overwrite existing files. |
| `--no-test` | \[Default: false] Whether to skip test generation.|
| `--application` | \[Optional] The application that provides the event. If omitted the service will try to guess it and raise an error if no application is found.|
| `--project-key` | \[Optional] The key of the project that the worker should belong to.|
| **Command arguments:** ||
| action | The name of the action to init (eg: BEFORE_DOWNLOAD). To have the list of all available actions use `jf worker list-event`. |
| worker-name | The name of the worker.|

This command will generate the following files:

- `manifest.json` – The worker specification which includes its name, the code location, the secrets and all the data that is useful to the worker.
- `package.json` – The file describing the development dependencies of the worker, this will not be used when executing your worker in our runtime.
- `worker.ts` – The worker code source, here it will be our sample code for the event.
- `worker.spec.ts` - The source code of the worker unit tests.
- `tsconfig.json` - The Typescript configuration file.
- `types.ts` - A file containing the event's specific types that can be used in the worker code.

## Example

Initialize a new BEFORE_DOWNLOAD worker named `my-worker`.

```
jfrog worker init BEFORE_DOWNLOAD my-worker
```
jf worker init BEFORE_DOWNLOAD my-worker
```
Loading