Edit

Update and manage modules you created

After you create and upload a module, you can update, delete, or change its visibility settings.

For information on pinning module deployments to versions, see Module versioning.

Update a module

Once your module is in the Viam Registry, there are two ways to update it:

Update automatically using GitHub Actions: Recommended for ongoing projects with continuous integration (CI) workflows, or if you want to build for multiple platforms.
- If you enabled cloud build when you generated your module, the GitHub Actions are already set up for you.
Update manually using the Viam CLI: Fine for small projects with one contributor.

Update automatically

Use GitHub Actions to automatically build and deploy your new module version when you create a tag or release in GitHub:

Edit your module code and update the meta.json file if needed. For example, if you’ve changed the module’s functionality, update the description in the meta.json file.
Make sure the url field contains the URL of the GitHub repo that contains your module code.
Push your changes to your module GitHub repository.
Note
If you used viam module generate to create your module and enabled cloud build, all you need to do to trigger a new build is create a tag and publish a release in GitHub as you did when you first published the module.

If you did not use the Viam CLI generator and enable cloud build, you can set up one of the following GitHub Actions up manually:

build-action (Recommended)
upload-module

The build-action GitHub action provides a cross-platform build setup for multiple platforms: x86, ARM Linux, and macOS.

In your repository, create a workflow file called build.yml in the .github/workflows directory:

on:
  push:
    tags:
      - "[0-9]+.[0-9]+.[0-9]+"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: viamrobotics/build-action@v1
        with:
          version: ${{ github.ref_name }}
          ref: ${{ github.sha }}
          key-id: ${{ secrets.viam_key_id }}
          key-value: ${{ secrets.viam_key_value }}

The build-action GitHub action relies on a build command that you need to specify in the meta.json file. At the end of your meta.json, add the build configuration:

{
  "module_id": "example-module",
  ...
  "build": {
    "setup": "./setup.sh", // optional - command to install your build dependencies
    "build": "./build.sh", // command that will build your module
    "path" : "dist/archive.tar.gz", // optional - path to your built module
    "arch" : ["linux/amd64", "linux/arm64"] // architecture(s) to build for
  }
}

Click to view example setup.sh

#!/bin/bash
set -e
UNAME=$(uname -s)
if [ "$UNAME" = "Linux" ]
then
echo "Installing venv on Linux"
sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
echo "Installing venv on Darwin"
brew install python3-venv
fi
python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt

Click to view example build.sh (with setup.sh)

#!/bin/bash
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

Click to view example build.sh (without setup.sh)

#!/bin/bash
set -e
UNAME=$(uname -s)
if [ "$UNAME" = "Linux" ]
then
echo "Installing venv on Linux"
sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
echo "Installing venv on Darwin"
brew install python3-venv
fi
python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt
python3 -m PyInstaller –onefile –hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

You can test this build configuration by running the Viam CLI’s build local command on your development machine:

viam module build local

The command will run your build instructions locally without running a cloud build job.

For more details, see the build-action GitHub Action documentation, or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs:

If you already have your own CI with access to arm runners or only intend to build on x86 or mac, you can use the upload-module GitHub action instead which allows you to define the exact build steps.

Add this to your GitHub workflow:

on:
  push:
  release:
    types: [released]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: build
        run: echo "your build command goes here" && false # <-- replace this with the command that builds your module's tar.gz
      - uses: viamrobotics/upload-module@v1
        # if: github.event_name == 'release' # <-- once the action is working, uncomment this so you only upload on release
        with:
          module-path: module.tar.gz
          platform: linux/amd64 # <-- replace with your target architecture, or your module will not deploy
          version: ${{ github.event_name == 'release' && github.ref_name || format('0.0.0-{0}.{1}', github.ref_name, github.run_number) }} # <-- see 'Versioning' section below for explanation
          key-id: ${{ secrets.viam_key_id }}
          key-value: ${{ secrets.viam_key_value }}

Set run to the command you use to build and package your module, such as invoking a makefile or running a shell script. When you are ready to test the action, uncomment if: github.event_name == 'release' to enable the action to trigger a run when you issue a release.

For guidance on configuring the other parameters, see the documentation for each:

org-id: Not required if your module is public.
platform: You can only upload one platform at a time.
version: See Using the –version argument for more details on the types of versioning supported.

For more details, see the upload-module GitHub Action documentation, or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs:

Create an organization API key with owner role:

viam organizations api-key create --org-id <org-id> --name <key-name>

Add the key ID and value as GitHub repository secrets named viam_key_id and viam_key_value.
Push a tag or create a release in GitHub to trigger the build. Once the build is complete, the module will automatically update in the Viam Registry, and the machines set to use the latest version of the module will automatically update to the new version.

Update manually

Use the Viam CLI to manually update your module:

Edit your module code and update the meta.json file if needed. For example, if you’ve changed the module’s functionality, update the description in the meta.json file.
For Python modules only, package your files as an archive, for example:
```
tar -czf module.tar.gz run.sh requirements.txt src
```
Supply the path to the resulting archive file in the next step.
Upload to the Viam Registry:
```
viam module upload --version <version> --platform <platform> <module-path>
```
For example, viam module upload --version 1.0.1 --platform darwin/arm64 my-module.tar.gz.

When you upload a module, the command performs basic validation of your module to check for common errors.

For more information, see the viam module command.

Change module visibility

You can change the visibility of a module from public to private if:

you are an owner of the organization that owns the module, AND
no machines outside of the organization that owns the module have the module configured (no other orgs are using it).

To change the visibility:

Navigate to your module’s page in the REGISTRY section of the Viam app.
Hover to the right of the visibility indicator near the right side of the page until an Edit button appears, and click it to make changes.

You can also edit the visibility by editing the meta.json file and then running the following CLI command:

viam module update

Delete a module

You can delete a module if:

you are an owner in the organization that owns the module, AND
no machines have the module configured.

To delete a module:

Navigate to its page in the REGISTRY section of the Viam app.
Click the … menu in the upper-right corner of the page, and click Delete.

Note

If you need to delete a module and the delete option is unavailable to you, please contact our support team for assistance.

Delete just one version of a module

Deleting a version of a module requires the same org owner permissions as deleting the entire module, and similarly, you cannot delete a version if any machines are using it. To delete just one version of a module:

Navigate to its page in the REGISTRY section of the Viam app
Click Show previous versions under the Latest version heading.
Hover on the architecture pill next to the version you’d like to delete and click the trash icon.

You cannot upload a new file with the same version number as the deleted one. To upload another version, you must increment the version number to a later version number.

Transfer ownership of a module

To transfer ownership of a module from one organization to another:

You must be an owner in both the current and new organizations.
Navigate to the module’s page in the REGISTRY section of the Viam app.
Make sure the visibility of the module is set to Public.
Click the … menu in the upper-right corner of the page, and click Transfer ownership.
Select the new organization from the dropdown menu, then click Transfer module.
(Recommended) Transfer the GitHub repository containing the module code to the new owner. Be sure to remove the existing secrets from the repository’s settings before transferring. If the repository is using Viam’s cloud build, the secrets contain an organization API key that will be exposed to the new owner after the repository transfer.
Update the meta.json file to reflect the new organization:
- Change the first part of the module_id field to the new organization’s namespace.
- For each model, change the first part of the model field to the new organization’s namespace.
- Update the url field to point to the new code repository if it has moved.
Update the module code:
- Throughout your module implementation code, change the model names in your component or service classes to match the changes you made to the meta.json file.
Run viam module update to push the changes to the registry.
Publish a new version of the module to the registry by following either set of update steps on this page. This ensures that the model names in the code match the registered model names in the registry.

Rename a module

If you need to change the name of a module, please reach out to the Viam team at support@viam.com.

Was this page helpful?

Glad to hear it! If you have any other feedback please let us know:

We're sorry about that. To help us improve, please tell us what we can do better:

Thank you!