5.5 Actions
The actions section allows unique functionalities that may significantly boost productivity when working with SPFx projects.
It is possible to:
Uses CLI for Microsoft 365 to create a .md report with upgrade guidance to the latest supported SPFx version by the extension. The upgrade guidance provides optional as well as required steps a user needs to take manually in order to upgrade the project. At the end of the guidance file, the user may find a summary of the steps in a single script and a couple of manual steps that need to be taken
Check it out in action 👇
Viva.vscode.R4.-.upgrade.mp4
For more information check out the spfx project upgrade command in the CLI for Microsoft 365 docs.
Creates a validation .md report against the currently used SPFx version in the project. The action will automatically detect the SPFx version used and will validate if the project is properly set up.
For more information check out the spfx project doctor in the CLI for Microsoft 365 docs.
The action will rename your project in the following places:
- package.json,
- .yo-rc.json,
- package-solution.json,
- deploy-azure-storage.json
- README.md.
When specified it will also generate a new solution ID.
Check it out in action 👇
For more information check out the spfx project rename in the CLI for Microsoft 365 docs.
The action will Grant all API permissions specified in the package-solution.json of the current project. This is especially helpful if you just want to debug your SPFx solution using Workbench. No longer do you need to bundle, package, and deploy the project to then go to the SharePoint admin portal and consent to the permissions. All of that is now done with just a single click
Check it out in action 👇
For more information check out the spfx project permissions grant in the CLI for Microsoft 365 docs.
This action will only work when the user is logged in to tenant and the sppkg file is present. The action will deploy the project to the selected (tenant or site) app catalog.
Check it out in action 👇
deploy.to.site.app.catalog.feature.mp4
For more information check out the spo app add and spo app deploy in the CLI for Microsoft 365 docs.
Allows scaffolding a new SPFx project as a new component of the currently opened project. The action under the hood uses the same SharePoint Yeoman generator to scaffold a new project and this feature is an abstraction UI layer. The extension will ask for the same information when adding a new component as the SPFx Yeoman generator. After that Viva Connections Toolkit will extend the currently opened project with a new component.
This action will allow you to generate yaml GitHub workflow that uses CLI for Microsoft 365 GitHub actions to bundle, package, and deploy your project to an app catalog on every code push.
Currently, this action only supports GitHub workflows as it generates a pipeline that uses CLI for Microsoft 365 GitHub actions. In the future, this feature will be extended to support other platforms like Azure DevOps, as well as automate more manual steps like registering an Azure app for the application authentication method.
Viva Connection Toolkit asks a couple of questions before generating the yaml pipeline but it's important to know that leaving everything as default will also generate a perfectly working workflow. Let's check out the default-generated yaml:
name: Deploy Solution test-solution
on:
push:
branches:
- main
workflow_dispatch: null
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/[email protected]
- name: Use Node.js 16.x
uses: actions/[email protected]
with:
node-version: 16.x
- name: Run npm ci
run: npm ci
- name: Bundle & Package
run: |
gulp bundle --ship
gulp package-solution --ship
- name: CLI for Microsoft 365 Login
uses: pnp/[email protected]
with:
CERTIFICATE_ENCODED: ${{ secrets.CERTIFICATE_ENCODED }}
CERTIFICATE_PASSWORD: ${{ secrets.CERTIFICATE_PASSWORD }}
APP_ID: ${{ secrets.APP_ID }}
- name: CLI for Microsoft 365 Deploy App
uses: pnp/[email protected]
with:
APP_FILE_PATH: sharepoint/solution/test-solution.sppkg
SKIP_FEATURE_DEPLOYMENT: true
OVERWRITE: true
Depending on the answers to each question the following modifications are made:
1. What should be the name of the workflow? (default: Deploy Solution ${name of sppkg file})
The answer to this question will set the name of the pipeline name: Deploy Solution test-solution. This is also then presented in GitHub Actions as the name of the workflow
2. What should be the branch name which should trigger the workflow on push? (default: main)
Here we may specify the branch name that will trigger the workflow on every push. This means every time we merge a commit or a PR to a specified branch the workflow will run.
3. Should it be possible to trigger the workflow manually?
If set to true (yes) it will allow you to run the workflow manually using the GitHub UI
4. Specify the login method used for the login action. (default: application)
Depending on the answer the CLI for Microsoft 365 Login GitHub action will be modified in the following way:
for application, the following yaml will be generated for this step (this is the default option)
- name: CLI for Microsoft 365 Login
uses: pnp/[email protected]
with:
CERTIFICATE_ENCODED: ${{ secrets.CERTIFICATE_ENCODED }}
CERTIFICATE_PASSWORD: ${{ secrets.CERTIFICATE_PASSWORD }}
APP_ID: ${{ secrets.APP_ID }}
for user, the following yaml will be generated for this step
- name: CLI for Microsoft 365 Login
uses: pnp/[email protected]
with:
ADMIN_USERNAME: ${{ secrets.ADMIN_USERNAME }}
ADMIN_PASSWORD: ${{ secrets.ADMIN_PASSWORD }}
5. Specify the scope of the app catalog. (default: tenant)
Here we may specify if we will deploy the app to tenant or site-level app catalog. When the site type is selected an additional question to specify the site app catalog url will be presented. For the site type the following yaml will be added to the last step
SCOPE: sitecollection
SITE_COLLECTION_URL: https://sharepoint.tenant.com/appcatalog
6. Specify the URL of the site collection where the solution package will be added
This is an optional question depending if site was selected in the previous question. The url specified in this answer will be used for the SITE_COLLECTION_URL option
7. Should the solution be deployed to the whole tenant? (applies when app supports tenant-wide deployment)
If set to true it will generate SKIP_FEATURE_DEPLOYMENT: true in the deploy step which means that if the package has an extension that supports tenan-wide deployment it will be automatically deployed to the whole tenant.
8. Should overwrite the solution package if it already exists in the app catalog?
This is the last question and setting this to true will automatically overwrite the package on the tenant if it is already present.
This action only generates the workflow yaml file. It does not do any additional setting on GitHub. Depending on which login method you select additional steps are needed.
For the application login method the command does not register AAD application nor create the required certificate. In order for you to proceed you will need to first obtain (create) a self-signed certificate and register a new AAD application with certificate authentication.
You may use the below script to generate a new self-signed certificate and register a new app in AAD with Sites.FullControl.All app-only permissions on SharePoint:
$password = ConvertTo-SecureString -String "my password" -Force -AsPlainText
$cert = New-SelfSignedCertificate -NotBefore $(Get-Date).AddDays(-1) -NotAfter $(Get-Date).AddYears(1) -FriendlyName "Certificate" -CertStoreLocation cert:\CurrentUser\My -Subject "CN=CICDCertificate" -KeyAlgorithm RSA -KeyLength 2048 -KeyExportPolicy Exportable
$cert | Export-Certificate -Type cer -FilePath "$PWD/Certificate.cer" -Force
$cert | Export-PfxCertificate -FilePath "$PWD/Certificate.pfx" -Password $password
$cert | Remove-Item
m365 aad app add --name 'Pipeline Application' --apisApplication 'https://microsoft.sharepoint-df.com/Sites.FullControl.All' --certificateFile ./Certificate.cer --certificateDisplayName 'pipeline Certificate' --grantAdminConsent
Depending on which authentication method was selected in GitHub repo settings, you will need to create the following secrets:
-
APP_ID- client id of the registered AAD application -
CERTIFICATE_ENCODED- application's encoded certificate -
CERTIFICATE_PASSWORD- certificate password. This applies only if the certificate is encoded which is the recommended approach
This use case is perfect in a production context as it does not create any dependencies on an account.
For the user login method you will need to create the following secrets in GitHub repo settings:
-
ADMIN_USERNAME- username -
ADMIN_PASSWORD- password
This use case is perfect for testing. It will not work if the specified account uses MFA.
Check it out in action 👇
For more information check out the spfx project github workflow add and how to automate your CI/CD workflow using CLI for Microsoft 365 GitHub Actions in the CLI for Microsoft 365 docs.
Viva Connections Toolkit supports a couple of sample galleries that may be used to scaffold a new SPFx project. The following gallery types are supported:
- SPFx Web Parts Samples - populated with samples from PnP Web Parts sample repo
- SPFx Extensions Samples - populated with samples from PnP Extensions sample repo
- ACE Scenarios - populated with samples from PnP ACEs scenario repo
- ACE Samples - populated with samples from PnP ACEs samples repo
To create a new project based on the sample directly from the view simply hit on the create button
