Open philliphoff opened 2 years ago
Thank you for this proposal 🙇 and sorry for the delay so far. I'll take a look in a bit!
Thanks for submitting this. Overall the approach makes sense to me. I think eventually we'd have to find a different approach to getting the starter workflows, when testing the branch I quickly blew through my user's rate limit for API calls, but starter workflows did show up 👍
The contribution approach where other extensions can contribute starter workflows also looks good overall.
For the extension itself, I think we'll have to do some design work to find a good entry point. Could be just a ➕ icon on the workflow list, but nicer might be a web-view or some buttons in the sidebar, something for us to figure out.
cc @andrewakim
Description
Deployment of "cloud native" components is becoming an integral component of the development process. GitHub (the website) provides a set of "starter" templates for GitHub Actions workflows, for various deployment scenarios, but there is no current means for this extension (or others) to reuse them. Furthermore, those templates often require additional user action before they can properly function, such as setting repository secrets and/or replacing tokens in the template content.
VS Code extensions have need to provide its users the ability to create deployment assets and automate their configuration. Some extensions will simply want to reuse the GitHub Actions workflow templates as-is, some will want to further automate their configuration, and some will want to offer completely new workflows.
The proposal is to have this extension offer its users (1) the direct means to create GitHub Actions workflows (e.g. via the command palette), both the existing GitHub Actions templates as well as any proffered by 3rd-party extensions, (2) the ability for 3rd-party extensions to further automate the creation of existing GitHub Actions templates, and (3) the ability for 3rd-party extensions to proffer their own workflow templates.
Goals
Non-goals
Extension API
This extension will export a versioned API to be used by 3rd-party extensions, both for initiating the creation of a specific workflow as well as to register itself as a contributor of workflow templates (or augmentor of existing "starter" workflow templates).
Package Configuration
3rd-party extensions contributing workflows declare them in
package.json
in one of two ways, depending on whether they are augmenting the existing "starter" workflows or creating their own.Augmenting "Starter" Workflows
Workflow contributions should include the following properties:
workflow
: The name of the starter workflow, which follows the<directory>/file[.yml]
in the actions/starter-workflows repository (i.e. omitting the.yml
).Custom Workflows
Custom workflow contributions should include the following properties:
workflow
: A unique name for the workflow typetitle
: The title of the workflow shown to users in a listdescription
: The description of the workflow shown to users in a listgroup
: The label under which the template should be grouped or, to be grouped with other templates, use one ofci
,deployments
,automation
, orcode-scanning
Usage
Creating workflows
Registering workflows
Concerns and Open Questions
Extension API Definition
What will be the best way for 3rd-party extensions to acquire the TypeScript definitions of this extension's API? Potential options are:
vscode-github-actions-api
NPM package"Starter" workflow template ownership
The proposal assumes that each contributed workflow type is owned by a single extension and this seems reasonable for unique workflow contributions. The proposal allows extensions to also augment the "starter" workflow templates; the proposal assumes (perhaps naively) that each template naturally maps to a single extension. In cases where that doesn't hold, where multiple extensions register providers for the same type of workflow, what should this extension do?
Potential options are:
Extension Activation
Because workflow contributions are declarative, this extension need not activate extensions contributing workflows unless and until immediately before their workflows are actually created. However, extensions which contribute workflows need access to this extension's API for registration during their activation. This implies that this extension's activation time will directly contribute to the overall activation time of contributing extensions. That is, care will need to minimize this extension's activation time.
Prototype Branch
https://github.com/philliphoff/vscode-github-actions/tree/philliphoff-create-workflow
Reviewers