So why would you want to write your own action? Reasons include:<\/p>\n
- \n
- Facilitate developer interaction with an existing API, service, or product. <\/li>\n
- Contribute to the DevSecOps ecosystem, reaching the 56+ million developers on GitHub. <\/li>\n
- Use Azure DevOps and GitHub Actions together<\/a> in a complementary fashion or while migrating<\/a> step by step<\/li>\n<\/ul>\n
The action we build in this guide will make it easy to upload files to Azure Blob Storage<\/a>, a service for massively scalable and secure storage of files like images, videos, logs, and backups. Let’s begin!<\/p>\n
Method<\/h2>\n
1\ufe0f\u20e3 Design the user experience<\/h3>\n
Start by designing a good user experience (UX):<\/p>\n
- \n
- How do we want someone to consume<\/em> the action? <\/li>\n
- How might someone already be used to interacting<\/em> with Azure Blob Storage programmatically, whether by Azure CLI<\/a>, popular SDKs<\/a>, or existing actions<\/a>? <\/li>\n
- What other actions or run steps<\/a> might commonly precede or follow<\/em> it?<\/li>\n<\/ul>\n
From some quick research, it looks like accepting a set of files (maybe supporting globbing) and an upload destination (maybe a storage account and container) is a good set of functionality to begin with. And maybe the action could be used in conjunction with some of the existing Azure actions<\/a>… \ud83e\udd14<\/p>\n
An action takes
inputs<\/code><\/a> and producesoutputs<\/code><\/a>, a model which lets actions be piped together with other actions, like these in the GitHub Marketplace<\/a>, in a workflow<\/a>. We can start with outputting thefilename<\/code> andurl<\/code> of the uploaded blob.<\/p>\nSo, a user experience like this should do the trick. Here’s an imaginary workflow calling the yet-to-be-built
upload-azure-blob<\/code> action:<\/p>\n# GitHub Actions repository workflow file, e.g .github\/workflows\/upload.yml\n\n# ...\n# previous steps to choose a runner type, authenticate to Azure, prepare files, etc\n# ...\n\n# Upload `.png`s to Azure Blob Storage\nname: Upload all PNGs to Azure Blob Storage\nid: upload\nuses: github-developer\/upload-azure-blob@v1\nwith:\n account: octodex\n destination: octocats\n source: **\/*.png\n\n# Print out the urls to uploaded files\nname: Print URLs\nrun: echo $URLS # { [\"filename\":\"hulatocat.png\",\"url\":\"https:\/\/octodex.blob.core.windows.net\/octocats\/hulatocat.png\"] }\nenv:\n URLS: ${{ steps.upload.outputs.urls }}\n<\/code><\/pre>\nQuick aside: an action is “just” a GitHub repository with a metadata file called
action.yml<\/code><\/a>. Workflows can call them using a pattern<\/a> likeuses: {owner}\/{repo}\/{path}@{ref}<\/code> \u2013 in the example above,uses: github-developer\/upload-azure-blob@v1<\/code>.<\/p>\nTo match the workflow above, the
action.yml<\/code> metadata file forupload-azure-blob<\/code> can look something like this. Progress!<\/p>\n# GitHub action metadata file, action.yml\n\n# ... name, description, branding\n\ninputs:\n account:\n description: |-\n Storage account name, e.g. 'mystorageaccount'\n required: true\n\n destination:\n description: |-\n Name of container to upload blob to, e.g. '$web' to upload a static website.\n required: true\n\n source:\n description: |-\n Path to file(s) to upload to \"destination\", e.g. '.' to upload all files in the current directory.\n Supports globbing, e.g. 'images\/**.png'.\n For more information, please refer to https:\/\/www.npmjs.com\/package\/glob.\n required: true\n\noutputs:\n urls:\n description: |-\n URL(s) to the uploaded blob(s), if successful\n\n# ...\n<\/code><\/pre>\nWith the metadata description complete, now we consider the action logic and come to a fork in the road.<\/p>\n
There are advantages to building a container action<\/a>, but arguably more for JavaScript actions<\/a>. They load faster, work on all runner types, and build upon a thriving community of tooling like
actions\/toolkit<\/code><\/a>! JavaScript also happens to be the most-used language across GitHub (read the Octoverse 2020 report<\/a>), so chances are, choosing JavaScript will open doors to community contribution to our action, too.<\/p>\nAnd you know what? Anything that compiles<\/em> to JavaScript is eligible, so let’s go with
CoffeeScript<\/del> errr nah, TypeScript<\/a>, for some extra DX love \ud83d\ude03. I’ve been wanting to try optional chaining<\/a> anyway.<\/p>\n2\ufe0f\u20e3 Get to coding<\/h3>\n
Start with a template<\/h4>\n
The GitHub Actions team provides a nice set of template repos<\/a>, ready to help us get started! By generating<\/a> a new repo from
actions\/typescript-action<\/code><\/a>, we start with a functioning action. Note that the name of this repository forms part of the path to your action. I generated mine intogithub-developer\/upload-azure-blob<\/code>, so it can be referenced that way across GitHub. Not to leave out all you container action devs, there’s a template or two<\/a> for you too.<\/p>\nAnd wow, to TypeScript eyes this action looks very…normal, except for that one stray metadata file,
action.yml<\/code>, most of which we designed before \u261d\ufe0f. Copy that in now.<\/p>\n.\n\u251c\u2500\u2500 .github\n\u2502 \u2514\u2500\u2500 workflows\n\u2502 \u2514\u2500\u2500 test.yml\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 LICENSE\n\u251c\u2500\u2500 README.md\n\u251c\u2500\u2500 __tests__\n\u2502 \u2514\u2500\u2500 main.test.ts\n\u251c\u2500\u2500 action.yml\n\u251c\u2500\u2500 jest.config.js\n\u251c\u2500\u2500 lib\n\u2502 \u251c\u2500\u2500 main.js\n\u2502 \u2514\u2500\u2500 wait.js\n\u251c\u2500\u2500 package-lock.json\n\u251c\u2500\u2500 package.json\n\u251c\u2500\u2500 src\n\u2502 \u251c\u2500\u2500 main.ts\n\u2502 \u2514\u2500\u2500 wait.ts\n\u2514\u2500\u2500 tsconfig.json\n<\/code><\/pre>\nThis action isn’t very useful for uploading to Azure Storage though \u2013 it just waits the number of
milliseconds<\/code> we input. But it’s a great base, since it does include compilation support, tests, a validation workflow, publishing, and versioning guidance!<\/p>\nLeverage official libraries and actions<\/h4>\n
We won’t get very far without access to an Azure SDK of some sort, like @azure\/storage-blob<\/a>. Used together<\/a> with
@azure\/identity<\/code><\/a>, we should be able to get an authenticated client to start make function \/ API calls. But “authenticated”… with what tokens? Whose identity? Well, we’re covered there, too \ud83d\ude0c.<\/p>\nThis TypeScript code we’re writing will be compiled and then called from a GitHub Actions workflow, right? And we saw earlier that there is an extensive set of actions just for Azure<\/a>. Well, one of these actions happens to facilitate secure, programmatic authentication with Azure on Actions runners<\/a>!<\/p>\n
So in our repository documentation (e.g.
README<\/code>), we can direct our users to callazure\/login<\/code><\/a> in their workflows beforeupload-azure-blob<\/code>, like this:<\/p>\n# GitHub Actions repository workflow file, e.g .github\/workflows\/upload.yml\n\n# ...\n# previous steps to choose a runner type, authenticate to Azure, prepare files, etc\n# ...\n\n# Log into Azure using repository secret with service principal credentials\n# https:\/\/github.com\/Azure\/login#configure-deployment-credentials\n- uses: azure\/login@v1\n with:\n creds: ${{ secrets.AZURE_CREDENTIALS }}\n\n# Upload `.png`s to Azure Storage Blob\n- uses: github-developer\/upload-azure-blob@v1\n with:\n account: mystorageaccount\n destination: nameofstoragecontainer\n source: **\/*.png\n<\/code><\/pre>\nIs that cool or what? Our function calls like these will suddenly work:<\/p>\n
\/\/ src\/upload.ts\nexport const getBlobServiceClient = (account: string): BlobServiceClient => {\n \/\/ https:\/\/github.com\/Azure\/azure-sdk-for-js\/blob\/master\/sdk\/identity\/identity\/README.md#defaultazurecredential\n const defaultAzureCredential = new DefaultAzureCredential()\n const blobServiceClient = new BlobServiceClient(\n `https:\/\/${account}.blob.core.windows.net`,\n defaultAzureCredential\n )\n return blobServiceClient\n}\n<\/code><\/pre>\nWrite the upload logic<\/h4>\n
Now we can write the logic to upload globbed blob (I just wanted to type that) paths like
*.log<\/code>,**\/*.png<\/code>. Yet again, we build on the shoulders of giants by pulling in a trusty npm package,glob<\/code><\/a>.<\/p>\nTo save us some time, and to spare you a very messy commit history (what, just me?!), here’s how the top-level
main.ts<\/code> shapes up, with the core functionality inupload.ts<\/code>. Refer to the full code in the the open source repo<\/a>.<\/p>\n\/\/ src\/main.ts\nimport * as core from '@actions\/core'\nimport { getInputs, getBlobServiceClient, uploadBlobs, Inputs, Output } from '.\/upload'\n\nasync function run (): Promise<void> {\n try {\n \/\/ Retrieve user inputs to action\n const inputs: Inputs = getInputs()\n \/\/ Retrieve authenticated container client\n const containerClient = getBlobServiceClient(inputs.account).getContainerClient(inputs.destination)\n \/\/ Upload files to container\n const output: Output[] = await uploadBlobs(containerClient, inputs.source)\n\n core.setOutput('urls', JSON.stringify(output))\n } catch (error) {\n core.setFailed(error.message)\n }\n}\n\n\/\/ eslint-disable-next-line @typescript-eslint\/no-floating-promises\nrun()\n<\/code><\/pre>\nOne distinction actions have with regular JavaScript projects is that dependent packages are committed alongside the code<\/a>, usually in a minified form using a compiler \/ bundler like @vercel\/ncc<\/a> or Parcel<\/a>. The
typescript-action<\/code> template already includesncc<\/code>, so by runningnpm run package<\/code>, you get a nice, compileddist\/index.js<\/code> file. This is the entry point to the action and should matchmain<\/code> inaction.yml<\/code>.<\/p>\nTest and automate<\/h4>\n
Of course, we should add some Jest unit tests to raise confidence in future changes \ud83d\ude07, and then we can use GitHub Actions as a test runner…to test our action! Let’s start with some quick sanity checks of
uploadBlobs<\/code>, just like you would with any other TypeScript project:<\/p>\n\/\/ __tests__\/upload.test.ts\n\n\/\/ ...\n\/\/ test files message1.txt, message2.txt exist in repo\n\/\/ ...\n\ntest('uploadBlobs doesn\\'t call uploadBlob with zero files', async () => {\n await upload.uploadBlobs(client, 'bananas.txt')\n expect(mockedUploadBlob.mock.calls.length).toBe(0)\n})\n\ntest('uploadBlobs calls uploadBlob with one file', async () => {\n await upload.uploadBlobs(client, 'message.txt')\n expect(mockedUploadBlob.mock.calls.length).toBe(1)\n})\n\ntest('uploadBlobs calls uploadBlob with two files', async () => {\n await upload.uploadBlobs(client, 'message*.txt')\n expect(mockedUploadBlob.mock.calls.length).toBe(2)\n})\n\n\/\/ ...\n<\/code><\/pre>\nYou could<\/em> try remember to run these tests locally or in GitHub Codespaces<\/a>, but it’s far better for them to run automatically every time a push happens or a pull request is opened. Sounds like a job for GitHub Actions! A sample continuous integration (CI) workflow<\/a> is included to build, test, and push compiled changes back to the repo.<\/p>\n
To view all the source code and see how you can pull in the action to your very own workflow, refer to this open source repo<\/a> \ud83e\udd17.<\/p>\n
3\ufe0f\u20e3 The action in action<\/h3>\n
So far, we have:<\/p>\n
- \n
- Designed <\/li>\n
- Developed <\/li>\n
- Tested <\/li>\n
- And automated CI for
upload-azure-blob<\/code> \ud83c\udf89<\/li>\n<\/ul>\nNow that we’ve built the engine, let’s see this thing go \ud83d\ude80! After creating an Azure storage account and container<\/a> and releasing
v1<\/code> of the action<\/a>, here’s me uploading some favorite octocats to my very own Octodex<\/a>:<\/p>\n![\"upload\"](\"https:\/\/user-images.githubusercontent.com\/2993937\/112677130-b377f880-8e3f-11eb-8880-ad0c6b1dde1d.gif\")
<\/p>\n4\ufe0f\u20e3 Release and publish to GitHub Marketplace<\/h3>\n
As it stands,
upload-azure-blob<\/code> is instructional but not necessarily production-ready. Here are just a few ideas of how it could be improved: – Automate release and maintenance (e.g. by following this guide<\/a>) – Remove requirement to have to create thedestination<\/code> before uploading to it – Increase test coverage<\/p>\nWhen we’re happy with the way things look, we can start to distribute and promote. How can I get this in more hands? Well for starters, anyone can publish actions<\/a> to GitHub Marketplace!<\/p>\n
When drafting a new release, it’s as simple as accepting the terms and clicking a checkbox:<\/p>\n
![\"publish-to-github-marketplace\"](\"https:\/\/user-images.githubusercontent.com\/2993937\/112678286-20d85900-8e41-11eb-9853-36ab18965b9f.gif\")
<\/p>\n
- How might someone already be used to interacting<\/em> with Azure Blob Storage programmatically, whether by Azure CLI<\/a>, popular SDKs<\/a>, or existing actions<\/a>? <\/li>\n
- How do we want someone to consume<\/em> the action? <\/li>\n