This repository contains the source code for the Speckle Automate GitHub Action. It is a GitHub Action that publishes a Speckle Automate Function definition to Speckle's automation platform.
[!NOTE] This is a low level building block action. As a Speckle Automate Function developer you probably want to use our composite action
speckle_automate_url
The URL of the Speckle Automate Server to publish the function to.
Defaults to https://automate.speckle.dev
.
speckle_token
The Speckle Automate API token to use to publish the function. This token must have functions:write
permissions.
This must be stored in GitHub as an encrypted secret. This token must be protected, as it allows anyone with access to it to publish functions as you to your Speckle Automate Server.
If you believe your token has been compromised, please revoke it immediately on your Speckle Automate Server. Please also audit your Speckle Automate Function changes to ensure that they were not made by an unauthorized party.
Please note that this is not a Speckle Account token, but a Speckle Automate API token. You can create one by logging into the Speckle Automate Server and going to the API Tokens page.
speckle_function_id
Associates this new version with the given ID of a Speckle Function.
Your Speckle Token must have write permissions for the Speckle Function with this ID, otherwise the publish will fail.
speckle_function_input_schema_file_path
Optional. The path to the JSON Schema file that describes the input schema for this version of the Speckle Function. This file is used to define the input form that will be presented to users when they compose an Automation based on this Function. If not provided, no input form will be presented to users. This can be an absolute path, or a path relative to the Home directory of the GitHub Action runner.
speckle_function_command
The command to run when this version of the Speckle Function is invoked. This command must be a valid command for the Docker image that contains the Speckle Function. This command must be a single string.
speckle_function_release_tag
The release tag for this version of the Speckle Function. This is intended to provide a more human understandable name for this version, and we recommend using the Git SHA of the commit used to generate this function version. The name must conform to the following:
speckle_function_recommended_cpu_m
Optional. The recommended maximum CPU in millicores for the function. If the Function exceeds this limit, it will be throttled to run within the limit.
1000 millicores = 1 CPU core. Defaults to 1000 millicores (1 CPU core).
speckle_function_recommended_memory_mi
Optional. The recommended maximum memory in mebibytes for the function. If the Function exceeds this limit, it will be terminated.
1024 mebibytes = 1 gibibyte. Defaults to 100 mebibytes.
version_id
The unique ID of this version of the published function.
speckle_automate_host
The host component of the Speckle Automate Server URL.
Speckle Automate GitHub Action will register a Speckle Function with Speckle Automate. This is a necessary, but not sufficient, step in publishing your Speckle Function. You must also build and push the Docker image that contains your Speckle Function.
uses: actions/speckle-automate-github-action@0.1.0
with:
# speckle_automate_url is optional and defaults to https://automate.speckle.dev
# The speckle_token is a secret and must be stored in GitHub as an encrypted secret
# https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow
speckle_token: "${{ secrets.SPECKLE_TOKEN }}"
speckle_function_id: "abcdefghij"
speckle_function_release_tag: "1.0.0"
uses: actions/speckle-automate-github-action@0.1.0
with:
# please update to the url of your self-hosted server
speckle_automate_url: https://example.org
# https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow
speckle_token: ${{ secrets.SPECKLE_TOKEN }}
speckle_function_id: "abcdefghij"
speckle_function_release_tag: "1.0.0"
Docker is the original, and still one of the most popular, ways to build and publish Docker images. It does require that you provide a Dockerfile, which includes instructions to Docker for building your image.
Find out more about Docker and Dockerfiles by following Docker's Get Started Guide.
You can learn more about Docker's GitHub Action from their documentation in the GitHub Actions Marketplace.
name: ci
on:
push:
branches:
- 'main'
jobs:
docker:
runs-on: ubuntu-latest
steps:
-
# Checkout the code
# Docker's GitHub Action does not require this step
# but Speckle Automate does
name: Checkout
uses: actions/checkout@v3
-
name: Set up QEMU
uses: docker/setup-qemu-action@v2
-
name: Set up Docker Buildx
uses: docker/setup-buildx-action@v2
-
name: Docker needs to login to Speckle Automate
uses: docker/login-action@v2
with:
username: ${{ secrets.SPECKLE_USERNAME }}
password: ${{ secrets.SPECKLE_TOKEN }}
-
name: Build and push
uses: docker/build-push-action@v4
with:
# ## file is optional and defaults to {context}/Dockerfile
# file: ./Dockerfile
# ## context is optional and defaults to the root directory '.' of the repository
# context: .
# ## platforms is optional and defaults to linux/amd64
# ## platforms must match the platforms that you have registered with Speckle Automate, which also defaults to linux/amd64.
# platforms: linux/amd64
push: true
# The name of the image to build and push.
# This must be the automate url host, followed by the function id, followed by the release tag.
tags: automate.speckle.dev/abcdefghij:1.0.0
-
id: speckle
name: Register Speckle Function
uses: actions/speckle-automate-github-action@0.1.0
with:
speckle_token: ${{ secrets.SPECKLE_TOKEN }}
speckle_function_id: "abcdefghij"
speckle_function_release_tag: "1.0.0"
yarn install
to install dependencies.yarn run all
to validate, build, and test the project.pre-commit install
to install the pre-commit hooksyarn install
to install dependenciesRun unit tests with coverage:
yarn test
Run unit tests and watch for changes while developing:
yarn test:watch
yarn precommit
to run all pre-commit hooks.Please make sure you read the contribution guidelines and code of conduct for an overview of the practices we try to follow.
The Speckle Community hangs out on the forum, do join and introduce yourself & feel free to ask us questions!
For any security vulnerabilities or concerns, please contact us directly at security[at]speckle.systems.
Unless otherwise described, the code in this repository is licensed under the Apache-2.0 License. Please note that some modules, extensions or code herein might be otherwise licensed. This is indicated either in the root of the containing folder under a different license file, or in the respective file's header. If you have any questions, don't hesitate to get in touch with us via email.