Feature request: GitHub Action

[matsev]

I would like to use asciidoctor/docker-ascidoctor as a GitHub Action so that I can render my documentation automatically when pushing changes to GitHub. Then another GitHub Action can publish the generated files, e.g. JamesIves/github-pages-deploy-action can be used to deploy to GitHub Pages.

The action should be configurable to render the documentation in all supported output formats (html, pdf and epub3). However, it is not necessary to support all formats at the same time, as one can configure different formats in different GitHub Action Steps.

Please read Creating a Docker container action for more information.

[dduportal]

Hello @matsev , thanks for reporting. It sounds like a legit request and would provide a nice value to the GitHub Action users.

cc @mojavelinux what do you think? Should we host the Action on this repository, or under another repository under the umbrella of the asciidoctor organization?

I volunteer by default to work on this, but anyone interested is welcome to particpate, lead and contribute to it of course!

[mojavelinux]

If it's feasible to host the action in this repository, I would think that might make management easier. However, if that clashes with the release cadence, then I'm open to making a new repo. In the latter case, we would need to decide on a name for the repository.

[fititnt]

Hi everyone. My 2 cents (from someone who is doing several GitHub actions on last weeks).

The GitHub guide actually recommends put GitHub actions as completely dedicated repository. It's strange at first, but then make sense. (This one os for Docker containers, https://docs.github.com/en/actions/creating-actions/creating-a-docker-container-action; is possible to make cross platform but it only make sense if project is supposed to interact with other tools).

(...) if that clashes with the release cadence

Yes, this is a point. If you are not 90% that most of the time it could be a different release cycle, is better to use a different repository. For a project like docker-asciidoctor it may actually be feasible put on same repository, but if was on asciidoctor, that would not be as friendly.

Also note that most of the time GitHub actions act as a 3rd level of indirection. So, the asciidoctor can have a version, the docker-asciidoctor can have another version, and then github actions asciidoctor have even another version. Also (important topic) the way GitHub actions is done, the default documentation will teach you to release actions that try to rebuild all packages with latest underlining versions all the time, so it's not 'a frozen' Dockerfile forever (but also the heavy caching, on layers on GitHub actions make it reasonable fast, maybe to a point of simply not worth the effort to pre-cache docker images if this is too hard to manage.

[fititnt]

Okay, based on this #112 (and pretty much others related to put more things on the container), I would suggest already create a different repository. First with docker-based, but leave it open to be written in the portable way (it could happens in months or years, but its relevant).

One additional reason for this is... license issues. Not kiding. The javascript/typescript version of github actions can run in any operacional system (but most people will use ubuntu-lastest), but one advantage here is actually it allows implementers be able to install these extra dependencies on their own risks. Also the non docker versions are even more faster to install (but the Docker version already is fast)

Anyway, instead of already aim to the portable version, just different repository already is great. The GitHub action actually don't need that much of update compared to the rest. Yet it might consider the first release of an official asciidoctor-action be a quick Dockerfile based. If you need help, you can do in one or two days. The hardest part is actually documentation since you may want to leave some "syntactic sugars", because people who uses GitHub actions want things more intuitive (and since is so easy to create then, you may love it!)

Anyway, I'm using the community github action of asciidoctor at https://github.com/EticaAI/hxltm. So if there is some early draft here, we from Etica.AI would love to be an early adopters!