Improve onboarding for storing badges on an orphan branch

[chris48s]

This is probably the ideal solution for where to store the badges. Currently this is just handled as a documentation point
https://github.com/action-badges/core/blob/main/docs/github-action.md#storing-your-badges

I tried this naive approach:

async function createOrphanBranch(client, { owner, repo, branch }) {
  const SHA1_EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
  const res = await client.request("POST /repos/{owner}/{repo}/git/commits", {
    owner,
    repo,
    message: "init orphan branch",
    tree: SHA1_EMPTY_TREE,
    parents: [],
  });
  await client.request("POST /repos/{owner}/{repo}/git/refs", {
    owner,
    repo,
    ref: `refs/heads/${branch}`,
    sha: res.data.sha,
  });
}

async function initOrphanBranch(client, { owner, repo, branch }) {
  try {
    await client.rest.repos.getBranch({ owner, repo, branch });
  } catch (e) {
    await createOrphanBranch(client, { owner, repo, branch });
  }
}

but it isn't concurrency-safe: If there are multiple workflows generating badges some of them will probably fail on the first run.
How can I do this in a concurrency-safe way?

[chris48s]

This used to be possible via the API but it doesn't work anymore. Here's a chopped down summary of my (long) chat with GitHub support that took place over ~ a month:

@chris48s wrote:

Hello.
I am trying to make an API request with the github REST API as per https://docs.github.com/en/rest/reference/git#commits .

The request I am trying to make is:

curl "https://api.github.com/repos/chris48s/orphan-branch-test/git/commits" \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  -H "Authorization: token <REDACTED: MY API TOKEN>" \
  --data '{"message":"init orphan branch","tree":"4b825dc642cb6eb9a060e54bf8d69288fbee4904","parents":[]}' \
  --include

(4b825dc642cb6eb9a060e54bf8d69288fbee4904 is the git empty tree hash so this request should work for any repo).

I've been able to a similar request successfully in the past, but today this is responding with a 500 status code and empty response body. AFAIK the request is correctly formed. Have I hit a bug with the API? A 500 error with empty response body doesn't seem like an expected error. It gives me no useful information on how to debug the error.

GitHub support wrote:

Hi again Chris,

I thought to follow up again on this report. The team confirmed that the passing of the empty tree does not work with the API but acknowledged the response returned should be better handled(i.e not returning a 500).

I can't make any promises if or when this change will be implemented but this is now being tracked by the right team.

@chris48s wrote:

I have a couple of follow-up questions about this.

1. I accept you "can't make any promises if or when this change will be implemented". However I am unclear from your message what "this change" would be. If implemented (which it might not be), would the change be:
   a) This API call still would not work, but a clearer error message would be returned?
   b) This API call would work?

2. The reason I am trying to make this API call to create a commit where the parent is the empty tree hash is because the task I'm trying to accomplish is creating an orphan branch via the API. Given this doesn't work, is there some other way to create an orphan branch via the API?

GitHub support wrote::

Thanks for the follow-up and sorry my response was confusing.

This API call still would not work, but a clearer error message would be returned?

Yes, this is what I meant.

The reason I am trying to make this API call to create a commit where the parent is the empty tree hash is because the task I'm trying to accomplish is creating an orphan branch via the API. Given this doesn't work, is there some other way to create an orphan branch via the API?

I'm afraid, there is no way to create an orphan branch via the API.

so.. long and short of this is trying to do this via the API is now a dead-end.

I think the options now are:

• Do it in javascript by shelling out to git
• Write a standalone action that creates an orphan branch using shell commands and then document that this can be used instead of https://github.com/action-badges/core/blob/main/docs/github-action.md#storing-your-badges

[chris48s]

For now I've settled on the following solution:

• Made a create-orphan-branch action
• Documented using that in https://github.com/action-badges/core/blob/main/docs/github-action.md#storing-your-badges in preference to creating one manually.

This is still not quite as elegant as I would ideally like.

[chris48s]

Maybe it is still worth looking at doing this in JS.
https://www.npmjs.com/package/simple-git is an option for a slightly higher level abstraction than shelling out directly using spawn(). Of course, then you're back to concurrency. At least with the Docker/bash action if you have multiple jobs, you can use needs to block everything on create-orphan-branch finishing. Once it is in the javascript black box it is really on me to make sure this 'just works'.

Not intrinsically connected to whether it is done using JS in core or using bash in a standalone action, but either way one thing I'm slightly worried about is leaving the working tree in an unexpected state. Currently create-orphan-branch handles this using:

• https://github.com/action-badges/create-orphan-branch/blob/5d32c8f393f042d5bd3257bfbbb01e310194712d/entrypoint.sh#L32-L34
• https://github.com/action-badges/create-orphan-branch/blob/5d32c8f393f042d5bd3257bfbbb01e310194712d/entrypoint.sh#L45-L46

Maybe git worktree would provide a more robust approach to this?

[chris48s]

Is there anything I can learn from https://github.com/s0/git-publish-subdir-action/blob/develop/action/src/index.ts ?