gactions user guide

This guide shows you how to use the gactions command line interface (CLI) tool in common usage scenarios. For information on building Actions end-to-end, see the Conversational Actions Build documentation.

Tip: To see more information when running commands, use the --verbose flag.

Project synchronization

When using the Actions SDK, gactions is your tool to synchronize Action projects between the Actions console and your local file system.

gactions pull operations export a project from the Actions console to your local file system, and gactions push operations push a project from your local file system to the Actions console.

Download Actions from Actions console

Run gactions pull to copy the configuration of an Actions project to the local file system.

The project-id of the project you want to copy can be passed on the command line, or written in the settings/settings.yaml file. If both are present, the CLI gives precedence to the value passed as an option.

mkdir -p myAction/sdk
cd myAction/sdk
gactions pull --project-id my-project-id
Pulling your project files from Draft for a project id: "my-project-id"
✔ Done. You should see the files written in path/to/myAction/sdk
ls -l
total 8
drwxr-x---  3 user  primarygroup   96 May  7 10:00 actions
drwxr-x---  4 user  primarygroup  128 May  7 10:00 custom
-rw-r-----  1 user  primarygroup   15 May  7 10:00 manifest.yaml
drwxr-x---  3 user  primarygroup   96 May  7 10:00 settings
vi settings/settings.yaml
// change projectId to "my-other-project-id"
gactions pull
Pulling your project files from Draft for a project id: "my-other-project-id"
path/to/myAction/sdk/manifest.yaml already exists. Would you like to overwrite it?. [y/n]
...
✔ Done. You should see the files written in path/to/myAction/sdk

The code snippet above shows how to pull an Action from project draft. It's also possible to pull from a specific version of your Action. A version represents a submitted copy of your Actions project, which could be deployed to a release channel.

The --version-id flag specifies which version to pull.

mkdir -p myAction/sdk
cd myAction/sdk
gactions pull --project-id my-project-id --version-id my-version-id
Pulling version "my-version-id" of the project "my-project-id" from Actions Console...
✔ Done. You should see the files written in path/to/myAction/sdk
ls -l
total 8
drwxr-x---  3 user  primarygroup   96 May  7 10:00 actions
drwxr-x---  4 user  primarygroup  128 May  7 10:00 custom
-rw-r-----  1 user  primarygroup   15 May  7 10:00 manifest.yaml
drwxr-x---  3 user  primarygroup   96 May  7 10:00 settings

Use the --force flag if you want to overwrite local copies of file without being asked for confirmation. Use the --clean flag to remove any of the local files that are not present in the remote Draft or Version. Use them together to get an exact copy of the Actions console project.

touch local_file.txt
gactions pull --force
Pulling your project files from Draft for a project id: "my-project-id"
[WARNING] 2020/05/07 17:34:32 path/to/myAction/sdk/local_file.txt is not present in the draft of your Action. To remove, run pull with --clean flag.
✔ Done. You should see the files written in path/to/myAction/sdk
gactions pull --force --clean
Pulling your project files from Draft for a project id: "my-project-id"
[WARNING] 2020/05/07 17:43:44 path/to/myAction/sdk/local_file.txt is not present in the draft of your Action. Removing path/to/myAction/sdk/local_file.txt.
✔ Done. You should see the files written in path/to/myAction/sdk

Push Actions to Actions console project draft

Run gactions push to push changes from the local file system to the Draft of your Action in the console. This process can be useful during development to view your changes reflected in the Actions console, without affecting the version that's served for testing.

gactions push
Pushing your project files to your Actions console draft for a project id: "my-project-id". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console: https://console.actions.google.com/project/my-project-id/overview to view your project. If you want to test your changes in the simulator, run "gactions deploy preview"

Import an existing project from a source code management system

If you want to work on an existing project from a revision in a version control system:

1. Check out the target revision (depends on the system).
2. Replace the value of projectId in the project's settings.yaml.
3. Optionally, run gactions push to copy the local configuration files to the Actions project.

git clone https://github.com/my/repo.git
Cloning into 'repo'...
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (9/9), done.
remote: Total 51 (delta 3), reused 3 (delta 1), pack-reused 41
Receiving objects: 100% (51/51), 36.86 KiB | 3.69 MiB/s, done.
Resolving deltas: 100% (11/11), done.
cd repo/sdk/
vi settings/settings.yaml
// change the value of `projectId`
gactions push

Listing versions

Run gactions versions list to view details about versions of your Action. To learn more about version statuses, refer to the reference for State.

gactions versions list
Version         Status          Last Modified By        Modified On     
1           Created     [e-mail]  2020-09-28 20:22:04

If the status of your deployment says "Creation failed", you can get more details about it in the Console under the "Release" section.

Deploy projects

The gactions deploy command lets you deploy your project to test in the Actions simulator or deploy to alpha/beta/production release channels.

Note: If you are using inline fulfillment in your Actions project, you must have a billing profile enabled before running the gactions deploy command. If you don't set up billing, you might run into errors deploying that can take 5-10 minutes to resolve before you can deploy again.

Preview in simulator

Run gactions deploy preview to deploy your Action to "preview", which lets you test your Action in the console, without actually updating the version of your Action project or impacting other developers. In other words, none of the changes you make in your local file system are propagated to deployed versions of your Actions project, but they are available to test on a preview version.

Note: This process requires at least the main invocation (custom/global/actions.intent.MAIN.yaml) to be defined.

gactions deploy preview
Deploying your project files to your Actions console preview for a project id: "my-project". This may take a few minutes.
Sending configuration files
Waiting for server to respond.
✔ Done. You can now navigate to the Actions Console simulator to test your changes: http://console.actions.google.com/project/my-project/simulator?disableAutoPreview

Create releases

Run gactions deploy to create version releases for alpha/beta/prod channels that you can manage through the Deploy section in the Actions console. Use it to test release candidates of your Action with your alpha and/or beta channels, and move the release candidate to production when you're satisfied with the feedback.

gactions deploy alpha
Deploying your project files to a actions.channels.Alpha channel for a project id: "my-project-id"
Sending configuration files
Waiting for server to respond.
✔ Done. Your Action was deployed to actions.channels.Alpha channel. You can check status of deployment in the Actions Console.

Listing release channels

Run gactions release-channels list to view details about release channels for your Action. You can use this command to identify the version deployed or pending to each channel.

gactions release-channels list
Release Channel             Current Version             Pending Version
alpha                   1                     N/A

Account linking

The gactions encrypt and gactions decrypt commands let you administer OAuth2 client secrets. These commands are specific to account linking.

Encrypt OAuth2 account linking client secrets

Run gactions encrypt to safely add client secrets for auth code OAuth2 account linking flows, or to encrypt existing secrets with a new encryption key.

gactions encrypt
Write your secret: *********************
Encrypting your client secret
path/to/myAction/sdk/settings/accountLinkingSecret.yaml already exists. Would you like to overwrite it?. [y/n]
y
✔ Done. Encrypted secret was written to path/to/myAction/sdk/settings/accountLinkingSecret.yaml

Access plain text value of encrypted account linking secrets.

Run gactions decrypt if you need to temporarily access the plain text value of the project's secret. The command prints the value to a text file of your choice. We recommend the destination file to be outside the root folder of the project, to avoid any accidental leak of the plain text value.

gactions decrypt ../../burn_after_read.txt
Decrypting your client secret
✔ Done. Check path/above/myActions/burn_after_read.txt to find decrypted client secret.
vi ../../burn_after_read.txt
rm ../../burn_after_read.txt