Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

The gihub.ref description is confusing and incorrect, particularly for PRs

Aberta
  • Algo errado?
#43,055 7 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 1 dia

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
68/100
Tipo de issue
Documentação
Clareza
Razoavelmente clara
Status de atividade
Ativa
Stack de tecnologia
github-actions
Domínio
documentation

Direção de pesquisa

Comece pelo artigo sobre o contexto do GitHub do GitHub Actions na URL docs.github.com vinculada e, em seguida, compare a descrição de github.ref com a documentação de eventos vinculada. Esclareça o comportamento de cada evento listado e reestruture o parágrafo em casos legíveis; o trabalho estará concluído quando a descrição estiver precisa e inequívoca.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

content github_actions never-stale
Code of Conduct
What article on docs.github.com is affected?

https://docs.github.com/en/actions/reference/workflows-and-actions/contexts#github-context

What part(s) of the article would you like to see updated?

The description for github.ref is confusing, misleading and incorrect, particularly for PR events.

The fully-formed ref of the branch or tag that triggered the workflow run. For workflows triggered by push, this is the branch or tag ref that was pushed. For workflows triggered by pull_request that were not merged, this is the pull request merge branch. If the pull request was merged, this is the head branch. For workflows triggered by release, this is the release tag created. For other triggers, this is the branch or tag ref that triggered the workflow run. This is only set if a branch or tag is available for the event type. The ref given is fully-formed, meaning that for branches the format is refs/heads/<branch_name>. For pull requests events except pull_request_target that were not merged, it is refs/pull/<pr_number>/merge. pull_request_target events have the ref from the base branch. For tags it is refs/tags/<tag_name>. For example, refs/heads/feature-branch-1.

Firstly, it's quite hard to follow the different branching logic of that parapgrah. Can this be formatted better, e.g. with nested bullet points?

Secondly, particularly for PR events, the logic is quite unclear, and incorrect in some places. The description mentions

pull requests events

but doesn't define them what these are. Is it the following subset of triggers?

Assuming this is the case, my understanding of the logic is as follows:

  1. pull_request events with a closed activity type that were merged: github.ref = refs/heads/<head_branch>
  2. All other pull_request events: github.ref = refs/pull/<pr_number>/merge
  3. All pull_request_target events (potentially excluding merged events): github.ref = refs/heads/<base_branch>
  4. issue_comment, pull_request_review and pull_request_review_comment (and potentially merged pull_request_target) events: github.ref = refs/pull/<pr_number>/merge

Problems to highlight:

  1. It's unclear whether "pull requests events except pull_request_target that were not merged" includes merged pull_request_target events. My tests suggest it doesn't; merged pull_request_target events show refs/heads/main, not refs/pull/<pr_number>/merge. What is this line trying to say?
  2. On a merged pull_request event, my tests show <base_branch>, not <head_branch>. There is a mistake in the description.
  3. For pull_request_target events, regardless of PR direction (main -> test or test -> main), my tests show refs/heads/main. Is it always the repo default, not the PR base?
  4. My tests show issue_comment events use refs/heads/main (regardless of PR direction), not refs/pull/<pr_number>/merge. Are these events not part of the PR logic? Does it always use the repo default?
  5. If we're being picky, there's a case to be made that "workflows triggered by pull_request that were not merged" means "closed and not merged" - meaning other activity types might not be included in the list. This could be worded better

Is the following summary more accurate?

  • All pull_request_target events: refs/heads/<default_branch>
  • Merged pull_request events: refs/heads/<base_branch>
  • All other pull_request events, and all pull_request_review and pull_request_review_comment events: refs/pull/<pr_number>/merge
  • issue_comment events: refs/heads/<default_branch>
Additional information

No response

Linguagem predominante
TypeScript
Estrelas
20.9k
Forks
68.9k
Merge médio
8h 3min
PRs com merge (30d)
116

Preparar o ambiente

Abrir no Codespaces

Inicia o contêiner de desenvolvimento do projeto no navegador, com a sua própria conta do GitHub.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de github/docs

Todas as issues de github/docs

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.