Interpolation of variables

[tenhobi]

In the

https://github.com/ad-m/github-push-action/blob/master/action.yml#L12
and
https://github.com/ad-m/github-push-action/blame/master/README.md#L35

there is interpolation used as {{ secrets.GITHUB_TOKEN }} and ${GITHUB_REPOSITORY}.

From the docs I think it should be ${{ <expression> }}. Should we change it to make it right?

[ad-m]

Yes.

Is there a solution that would synchronize the documentation with the manifest, so that we would be in compliance in the future?

[tenhobi]

That would be possibly only by running some script manually each time, or by running Action what whould parse the yaml to the right markdown part.

For example you would put some tag like this below to the README and the Action would insert new content to it each time on push to master.

<div action-inputs></div>

And it could work for other data from that file too.

That might be interesting, in fact, will we do something like that?

[tenhobi]

On the other hand, I can see no repository which has mentioned its inputs in README. :/

[ad-m]

I would not see it as a single tag, but a separate section <!-- action-doc-start-->...<!-- action-doc-end-->, which the script would automatically fill. In the event of a change, the script would change the content of the section, and our action could automatically commit the changes. In the absence of any changes, the script would not change the content of the section, so there would be no changes to be posted.

It's possible that others are waiting for GitHub to properly document this.

[tenhobi]

Maybe we should also wait for final version. Not it's in alpha, beta or something. :-)

[ad-m]

@damccorm are you aware any plans in area of GitHub-provided documentation for actions inputs? Can you share them so that we can decide if it's worth working on it?

[damccorm]

Not that I know of, @rachmari would probably know better than I

[rachmari]

@ad-m we plan to write a short guide that will show people writing a workflow how to use inputs and outputs. For example, it would show you how to supply an action in a workflow with its required inputs and retrieve the output from that action. We'll also explain how a someone developing an action can use inputs and set outputs. We already do that a bit in these two guides:

• Creating a JavaScript action
• Creating a Docker container action

We recommend that anytime you create an action that you include the inputs and outputs that the action requires in the README file of the repository. We are working on ensuring that all repositories in the github.com/actions organization also follow those best practices. You can see an example README that declares the required or optional inputs/outputs here.

Let me know if you have any more questions. ✨

[ad-m]

So there is no plan to parse action.yml by GitHub, if I understand correctly. Users have to convert action.yml to README by self, not as part eg. GitHub Marketplace of GitHub Actions.

[rachmari]

That's a great question. I'm not sure if we plan to do that for actions in Github Marketplace. @ethomson do you know the plans for that?

[ad-m]

In my opinion - since action.yml contains all necessary information, there is no reason for users to manually write documentation in regard of input and output. It is prone to erroneous and difficult to automatically verify. If GitHub Marketplace for GitHub Actions will not automatically present the information currently contained in action.yml, we will have to update README.md automatically eg. by another actions. PR #14 is an example that content in README.md and action.yml is duplicated and therefore prone to errors.

[ethomson]

We're thinking about a change to take the action.yml and show some information in the GitHub Marketplace about how to use an action based on that.

[ethomson]

If we do this, though, it will be a display of the data in the action.yml only. It's not meant as a replacement for your README, which can show a full workflow, including applicable runs-on environments, preconditions like actions/checkout, etc. That information isn't in the action.yml, so I don't think you should think of this behavior in the GitHub Marketplace as removing the need for a good sample workflow.

[ad-m]

In my opinion, OpenAPI is a good example of documentation that is machine-processable (suitable for visualization) but understood by human. I suggest analyse how this specs provides for the possibility of placing examples (purely for information purposes). As I know action.yml can not contains examples.

If GitHub Marketplace for GitHub Actions will provide a convenient API for information in action.yml, in addition to visualizing this information, you will be able to integrate this solution with editors to get automatic hints on the parameters provided by the actions.

[ad-m]

Thank you for the information that GitHub plans to publish in an attractive way information about "input" and "output". In this case, we can stop our work on automatically updating README.md based on this.