DocC Tutorial for Swift: Automating Publishing With GitHub Actions

Running the Workflow on GitHub Actions

If you haven’t yet created your repository locally, run:

git init

As this is a new repository, all your changes are file additions. After staging them, create an initial commit. Then, add the GitHub remote. Replace your username and the repository name before running this command:

git remote add origin https://github.com/<your-username>/<your-repository-name>.git

Create the main branch, and push your changes:

git branch -M main && git push -u origin main

After pushing it to GitHub, open your repository page, and go to the Actions tab. In the list, you’ll see the Action you just created, within a few moments, in the queued state.

In some cases, the Action might get stuck in the queued state. If that’s the case, you’ve already defined the workflow_dispatch event in the workflow, which allows manually triggering the Action.

After moving from the queued to the running state, click the workflow run in the list to see more details:

Notice how, in the image above, there’s a line between the build and deploy. It represents the dependency of the deploy job on the build job.

After a few minutes, both jobs should be complete:

As you can see, both jobs have green check marks, making the run itself a successful one. Under deploy, you’ll see a link. Clicking it will take you to https://<your-username>.github.io/<repository-name>, and the browser will display the documentation you worked so hard to publish:

Where to Go From Here?

You can download the completed project files by clicking Download materials at the top or bottom of the tutorial.

Congratulations on reaching the end of this tutorial! It included many steps: writing a shell script, creating a repository, enabling GitHub Pages on it, defining your workflow file and running it. If you made it here, it means you learned and acquired new skills.

If you already feel the superpowers of automating your processes, you might want to expand your knowledge in the CI/CD space, deepen your expertise in GitHub Actions, and also in technologies or services that host static content and make its distribution even faster with content delivery networks (CDNs). Here’s what you could do next:

• Wrap your frequently used steps into a shareable Action of your own.
• Connect to the web: Automate calling your workflows via webhooks and also call external webhooks from your workflow steps.
• Automate generation of Swift code that compiles on Linux, using the DocC Swift Package Manager plugin, instead of relying on Xcode and macOS. By doing so, you don’t need to use the macOS runners. The Linux runners will be enough, which is a positive factor since they consume fewer credits than the macOS ones.
• Publish your documentation to other services, such as Netlify, which provides a CDN on top of hosting.

We hope you enjoyed this tutorial, and if you have any questions or comments, please join the forum discussion below!