From 9330b5e49ceb706051123323170a6fcc5755760f Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Fri, 11 Oct 2024 14:57:22 +0200 Subject: [PATCH 1/3] feat(create-plugin): add a create-plugin update workflow template file --- .../templates/github/workflows/cp-update.yml | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 packages/create-plugin/templates/github/workflows/cp-update.yml diff --git a/packages/create-plugin/templates/github/workflows/cp-update.yml b/packages/create-plugin/templates/github/workflows/cp-update.yml new file mode 100644 index 000000000..3589d3c4a --- /dev/null +++ b/packages/create-plugin/templates/github/workflows/cp-update.yml @@ -0,0 +1,25 @@ +name: Create Plugin Update + +on: + workflow_dispatch: + schedule: + - cron: '0 0 1 * *' # run once a month on the 1st day + +# To use the default github token with the following elevated permissions make sure to check: +# **Allow GitHub Actions to create and approve pull requests** in https://github.com/USER_NAME/REPO_NAME/settings/actions. +# Alternatively create a fine-grained personal access token for your repository with `contents: read and write` and `pull requests: read and write` and pass it to the action. + +permissions: + contents: write + pull-requests: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: grafana/plugin-actions/create-plugin-update@main + # Uncomment to use a fine-grained personal access token instead of default github token + # (For more info on how to generate the token see https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) + # with: + # Make sure to save the token in your repository secrets + # token: ${{ secrets.GH_PAT_TOKEN }} From cf6688bf0c37e93423d66d1a58abafb31bd0ec11 Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Fri, 11 Oct 2024 15:00:12 +0200 Subject: [PATCH 2/3] chore(create-plugin): update workflow comments --- .../create-plugin/templates/github/workflows/cp-update.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/create-plugin/templates/github/workflows/cp-update.yml b/packages/create-plugin/templates/github/workflows/cp-update.yml index 3589d3c4a..6cf66eba5 100644 --- a/packages/create-plugin/templates/github/workflows/cp-update.yml +++ b/packages/create-plugin/templates/github/workflows/cp-update.yml @@ -6,8 +6,9 @@ on: - cron: '0 0 1 * *' # run once a month on the 1st day # To use the default github token with the following elevated permissions make sure to check: -# **Allow GitHub Actions to create and approve pull requests** in https://github.com/USER_NAME/REPO_NAME/settings/actions. -# Alternatively create a fine-grained personal access token for your repository with `contents: read and write` and `pull requests: read and write` and pass it to the action. +# **Allow GitHub Actions to create and approve pull requests** in https://github.com/ORG_NAME/REPO_NAME/settings/actions. +# Alternatively create a fine-grained personal access token for your repository with +# `contents: read and write` and `pull requests: read and write` and pass it to the action. permissions: contents: write From ec51a1246cd9554e928ec608bf5870bb5fbc420a Mon Sep 17 00:00:00 2001 From: Jack Westbrook Date: Fri, 11 Oct 2024 15:47:34 +0200 Subject: [PATCH 3/3] docs(website): add an entry for cp update workflow to getting started dev env doc --- .../set-up-development-environment.mdx | 67 ++++++++++++++++--- 1 file changed, 58 insertions(+), 9 deletions(-) diff --git a/docusaurus/docs/get-started/set-up-development-environment.mdx b/docusaurus/docs/get-started/set-up-development-environment.mdx index aeab06f4e..a2a220794 100644 --- a/docusaurus/docs/get-started/set-up-development-environment.mdx +++ b/docusaurus/docs/get-started/set-up-development-environment.mdx @@ -20,6 +20,7 @@ import DockerPNPM from '@snippets/docker-grafana-version.pnpm.md'; import DockerYarn from '@snippets/docker-grafana-version.yarn.md'; This guide walks you through setting up your development environment for Grafana plugin development. Including: + - Running a development Grafana server with your plugin installed using Docker - Setting up GitHub workflows to automate your development and release process - Extending configurations for ESLint, Prettier, Jest, TypeScript, and Webpack @@ -117,6 +118,7 @@ For example, in VSCode, you can add a `launch.json` configuration like this: ``` You can control the go version and the architecure used to build your plugin in the docker compose by setting `GO_VERSION` and `GO_ARCH` environment variables: + ```yaml title="docker-compose.yaml" version: '3.7' @@ -133,11 +135,11 @@ services: You will also notice that the `docker-compose.yaml` file also has the following settings: ```yaml title="docker-compose.yaml" - security_opt: - - "apparmor:unconfined" - - "seccomp:unconfined" - cap_add: - - SYS_PTRACE +security_opt: + - 'apparmor:unconfined' + - 'seccomp:unconfined' +cap_add: + - SYS_PTRACE ``` they are necessary to allow delve to attach to the running process and debug it and should not be used in production environments. @@ -178,7 +180,7 @@ This workflow requires a Grafana Cloud API key. Before you begin, follow the ins Once the secret is stored, you can access it in your GitHub Actions workflow: -```json title="release.yml" +```yaml title="release.yml" name: Release jobs: @@ -189,7 +191,6 @@ jobs: - uses: grafana/plugin-actions/build-plugin@release with: grafana_token: ${{ secrets.GRAFANA_ACCESS_POLICY_TOKEN }} - ``` In this example, the `secrets.GRAFANA_ACCESS_POLICY_TOKEN` variable is used to access the stored token securely within your GitHub Actions workflow. Make sure to adjust the workflow according to your specific needs and the language/environment you are working with. @@ -203,7 +204,7 @@ git tag v1.0.0 git push origin v1.0.0 ``` -### The compatibility check (`is-compatible.yml`) +### The compatibility check workflow The compatibility check (`is-compatible.yml`) workflow is designed to check the Grafana API compatibility of your plugin every time you push changes to your repository. This helps to catch potential frontend runtime issues before they occur. @@ -215,6 +216,55 @@ The workflow contains the following steps: 1. Looking for usages of those changed APIs inside your plugin. 1. Reporting any potential incompatibilities. +### The create plugin update workflow + +The create plugin update (`cp-update.yml`) workflow is designed to automate keeping your plugins development environment and dependencies up to date. It periodically checks the latest version of create-plugin listed on the npm registry and compares it to the version used by your plugin. If there is a newer version available the workflow will run the `create-plugin update` command, update the frontend dependency lockfile, then create a PR with the changes for review. + +This workflow requires content and pull request write access to your plugins repo to be able to push changes and open PRs. Choose from the following two options: + +#### Use the default access token + +To use this option you must allow [github actions to create and approve pull requests](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests) within your repository settings and use the `permissions` property in the workflow to elevate the default access token permissions like so: + +```yaml +name: Create Plugin Update + +on: + workflow_dispatch: + schedule: + - cron: '0 0 1 * *' # run once a month on the 1st day + +permissions: + contents: write + pull-requests: write + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: grafana/plugin-actions/create-plugin-update@main +``` + +#### Use a personal access token + +To use this option you must create a Github [fine-grained personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with access to the plugin repository and permission to read and write both `contents` and `pull requests`. Once created add the token to the plugin repository action secrets and then pass it to the action like so: + +```yaml +name: Create Plugin Update + +on: + workflow_dispatch: + schedule: + - cron: '0 0 1 * *' # run once a month on the 1st day + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: grafana/plugin-actions/create-plugin-update@main + with: + token: ${{ secrets.GH_PAT_TOKEN }} +``` ## Extend configurations @@ -389,4 +439,3 @@ Update the `scripts` in the `package.json` to use the extended Webpack configura -"dev": "webpack -w -c ./.config/webpack/webpack.config.ts --env development", +"dev": "webpack -w -c ./webpack.config.ts --env development", ``` -