Wolfram Language Paclet Repository
Community-contributed installable additions to the Wolfram Language
GitHub Actions Quick Start
GitHub Actions Quick Start
Prerequisites
Prerequisites
A GitHub Account
A GitHub Account
This tutorial assumes that you already have a GitHub account and are familiar with the basics of git. If not, the following links will be a useful starting place:
A GitHub Repository
A GitHub Repository
You'll need a GitHub repository where you have sufficient permissions to modify repository settings and push commits.
If you do not yet have a repository, but want to try out PacletCICD functionality, you can the following repository to serve as a starter template:
Setup
Setup
Load the PacletCICD package:
In[1]:=
Needs["Wolfram`PacletCICD`"];
Define the directory where your paclet files are stored:
In[1]:=
$pacletDirectory=File["C:\\GitHub\\PacletCICD-Examples-Sample"];
Specify which directory corresponds to the Git repository (this is often the same as the paclet directory):
In[2]:=
$gitDirectory=File["C:\\GitHub\\PacletCICD-Examples-Sample"];
These locations will be used throughout this tutorial.
Creating a Build Workflow
Creating a Build Workflow
Create and Export
Create and Export
In[1]:=
workflow=
["Build"]
 | Workflow |
Out[1]=
Workflow
 |  |
|
Export the workflow to your paclet:
In[2]:=
 | WorkflowExport |
Out[2]=
File
C:\GitHub\PacletCICD-Examples-Sample\.github\workflows\Build.yml |
Check the contents of the exported file:
In[3]:=
FilePrint[%]
name: Build
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
jobs:
Build:
name: Build
runs-on: ubuntu-latest
container:
image: wolframresearch/wolframengine:latest
options: --user root
env:
WOLFRAM_SYSTEM_ID: Linux-x86-64
WOLFRAMSCRIPT_ENTITLEMENTID: ${{ secrets.WOLFRAMSCRIPT_ENTITLEMENTID }}
RESOURCE_PUBLISHER_TOKEN: ${{ secrets.RESOURCE_PUBLISHER_TOKEN }}
steps:
- name: Checkout
id: checkout-code-step
uses: actions/checkout@v2
- name: Build
id: build-paclet-step
uses: WolframResearch/build-paclet@v1.7.1
with:
target: Submit
paclet_cicd_version: 0.19.1
definition_notebook: ./ResourceDefinition.nb
resource_system_base: https://www.wolframcloud.com/obj/resourcesystem/api/1.0
- name: UploadArtifact
id: upload-build-artifacts-step
uses: actions/upload-artifact@v2
with:
path: ${{ env.PACLET_BUILD_DIR }}
if-no-files-found: ignore
on:
push:
branches: [main]
pull_request:
branches: [main]
workflow_dispatch:
jobs:
Build:
name: Build
runs-on: ubuntu-latest
container:
image: wolframresearch/wolframengine:latest
options: --user root
env:
WOLFRAM_SYSTEM_ID: Linux-x86-64
WOLFRAMSCRIPT_ENTITLEMENTID: ${{ secrets.WOLFRAMSCRIPT_ENTITLEMENTID }}
RESOURCE_PUBLISHER_TOKEN: ${{ secrets.RESOURCE_PUBLISHER_TOKEN }}
steps:
- name: Checkout
id: checkout-code-step
uses: actions/checkout@v2
- name: Build
id: build-paclet-step
uses: WolframResearch/build-paclet@v1.7.1
with:
target: Submit
paclet_cicd_version: 0.19.1
definition_notebook: ./ResourceDefinition.nb
resource_system_base: https://www.wolframcloud.com/obj/resourcesystem/api/1.0
- name: UploadArtifact
id: upload-build-artifacts-step
uses: actions/upload-artifact@v2
with:
path: ${{ env.PACLET_BUILD_DIR }}
if-no-files-found: ignore
Note the and environment variables. These will need to be defined for your repository in the next step in order for the workflow to run.
Define GitHub Secrets
Define GitHub Secrets
These only need to be defined once per repository (or until they expire).
WOLFRAMSCRIPT_ENTITLEMENTID
This environment variable corresponds to an on-demand license entitlement that allows the Wolfram Engine kernel to run in a GitHub hosted runner. To create an entitlement, use with the following recommended settings:
In[1]:=
entitlement=CreateLicenseEntitlement["StandardKernelLimit"16,"LicenseExpiration"Quantity[30,"Minutes"],"EntitlementExpiration"Quantity[1,"Months"]]
Out[1]=
LicenseEntitlementObject
|  |
|
Copy the entitlement ID to the clipboard by either clicking in the output above, or evaluate the following:
In[2]:=
CopyToClipboard[entitlement["EntitlementID"]]
Visit the following URL (replacing {user} and {repo} to match your repository) to define a repository secret:
https://github.com/{user}/{repo}/settings/secrets/actions
Click the "New repository secret" button at the top-right:
Use WOLFRAMSCRIPT_ENTITLEMENTID as the name, and paste in the entitlement string as the value, then click the "Add secret" button:
Your GitHub repository is now configured to run Wolfram Engine kernels in workflows.
RESOURCE_PUBLISHER_TOKEN
This environment variable corresponds to a token that's issued by the resource system that allows you to authenticate some requests without full cloud authentication. This avoids the need to store the more sensitive credentials that would be required for .
In[1]:=
token=
["Example","AllowedEndpoints"All]
| CreatePublisherToken |
Out[1]=
PublisherTokenObject
|  |
|
Click to copy the token string from the output above, or evaluate the following to extract it from the :
PublisherTokenObject
In[2]:=
CopyToClipboard[token["TokenString"]]
Visit the following URL (replacing {user} and {repo} to match your repository) to define a repository secret:
https://github.com/{user}/{repo}/settings/secrets/actions
Click the "New repository secret" button at the top-right:
Use RESOURCE_PUBLISHER_TOKEN as the name, and paste in the token string as the value, then click the "Add secret" button:
Push Changes
Push Changes
Set the current directory to the location of your Git repository:
In[1]:=
SetDirectory[$gitDirectory];
Stage the workflow file that was created earlier:
In[2]:=
git add .github/workflows/Build.yml
Commit the changes:
In[3]:=
git commit -m 'Added a build workflow'
Push the changes to GitHub:
In[3]:=
git push
The workflow should now be running automatically. To see the current status, visit the following URL (replacing {user} and {repo} to match your repository):
https://github.com/{user}/{repo}/actions
Click on the currently running workflow to see its status:
When the workflow is complete, the built paclet will be available as a downloadable file on the summary page:
""