Pontos de extremidade da API REST para políticas de branch de implantação

Sobre as políticas de branch de implantação

Use a API REST para especificar padrões de nome personalizados aos quais os branches devem corresponder para a implantação em um ambiente. A propriedade deployment_branch_policy.custom_branch_policies do ambiente deve ser definida como true para usar esses pontos de extremidade. Para atualizar o deployment_branch_policy para um ambiente, confira Pontos de extremidade da API REST para ambientes de implantação.

Para saber mais sobre como restringir implantações de ambiente a determinados branches, confira Gerenciar ambientes para implantação.

List deployment branch policies

Lists the deployment branch policies for an environment.

Anyone with read access to the repository can use this endpoint.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

Tokens de acesso refinados para "List deployment branch policies"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

"Actions" repository permissions (read)

Esse ponto de extremidade pode ser usado sem autenticação ou as permissões acima mencionadas se apenas recursos públicos forem solicitados.

Parâmetros para "List deployment branch policies"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`owner` string Obrigatório The account owner of the repository. The name is not case sensitive.
`repo` string Obrigatório The name of the repository without the `.git` extension. The name is not case sensitive.
`environment_name` string Obrigatório The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with `%2F`.

Parâmetros de consulta
Nome, Tipo, Descrição
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Padrão: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Padrão: `1`

Códigos de status de resposta HTTP para "List deployment branch policies"

Código de status	Descrição
`200`	OK

Exemplos de código para "List deployment branch policies"

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

get/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies

Response

Status: 200

{
  "total_count": 2,
  "branch_policies": [
    {
      "id": 361471,
      "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjE0NzE=",
      "name": "release/*"
    },
    {
      "id": 361472,
      "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjE0NzI=",
      "name": "main"
    }
  ]
}

Create a deployment branch policy

Creates a deployment branch or tag policy for an environment.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

Tokens de acesso refinados para "Create a deployment branch policy"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

"Administration" repository permissions (write)

Parâmetros para "Create a deployment branch policy"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`owner` string Obrigatório The account owner of the repository. The name is not case sensitive.
`repo` string Obrigatório The name of the repository without the `.git` extension. The name is not case sensitive.
`environment_name` string Obrigatório The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with `%2F`.

Parâmetros do corpo
Nome, Tipo, Descrição
`name` string Obrigatório The name pattern that branches or tags must match in order to deploy to the environment. Wildcard characters will not match `/`. For example, to match branches that begin with `release/` and contain an additional single slash, use `release//`. For more information about pattern matching syntax, see the Ruby File.fnmatch documentation.
`type` string Whether this rule targets a branch or tag Pode ser um dos: `branch`, `tag`

Códigos de status de resposta HTTP para "Create a deployment branch policy"

Código de status	Descrição
`200`	OK
`303`	Response if the same branch name pattern already exists
`404`	Not Found or `deployment_branch_policy.custom_branch_policies` property for the environment is set to false

Exemplos de código para "Create a deployment branch policy"

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em api.SUBDOMAIN.ghe.com.

Exemplos de solicitação

Select the example type

post/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies \
  -d '{"name":"release/*"}'

Response

Status: 200

{
  "id": 364662,
  "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
  "name": "release/*"
}

Get a deployment branch policy

Gets a deployment branch or tag policy for an environment.

Anyone with read access to the repository can use this endpoint.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint with a private repository.

Tokens de acesso refinados para "Get a deployment branch policy"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

"Actions" repository permissions (read)

Esse ponto de extremidade pode ser usado sem autenticação ou as permissões acima mencionadas se apenas recursos públicos forem solicitados.

Parâmetros para "Get a deployment branch policy"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`owner` string Obrigatório The account owner of the repository. The name is not case sensitive.
`repo` string Obrigatório The name of the repository without the `.git` extension. The name is not case sensitive.
`environment_name` string Obrigatório The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with `%2F`.
`branch_policy_id` integer Obrigatório The unique identifier of the branch policy.

Códigos de status de resposta HTTP para "Get a deployment branch policy"

Código de status	Descrição
`200`	OK

Exemplos de código para "Get a deployment branch policy"

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

get/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies/BRANCH_POLICY_ID

Response

Status: 200

{
  "id": 364662,
  "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
  "name": "release/*"
}

Update a deployment branch policy

Updates a deployment branch or tag policy for an environment.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

Tokens de acesso refinados para "Update a deployment branch policy"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

"Administration" repository permissions (write)

Parâmetros para "Update a deployment branch policy"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`owner` string Obrigatório The account owner of the repository. The name is not case sensitive.
`repo` string Obrigatório The name of the repository without the `.git` extension. The name is not case sensitive.
`environment_name` string Obrigatório The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with `%2F`.
`branch_policy_id` integer Obrigatório The unique identifier of the branch policy.

Parâmetros do corpo
Nome, Tipo, Descrição
`name` string Obrigatório The name pattern that branches must match in order to deploy to the environment. Wildcard characters will not match `/`. For example, to match branches that begin with `release/` and contain an additional single slash, use `release//`. For more information about pattern matching syntax, see the Ruby File.fnmatch documentation.

Códigos de status de resposta HTTP para "Update a deployment branch policy"

Código de status	Descrição
`200`	OK

Exemplos de código para "Update a deployment branch policy"

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

put/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies/BRANCH_POLICY_ID \
  -d '{"name":"release/*"}'

Response

Status: 200

{
  "id": 364662,
  "node_id": "MDE2OkdhdGVCcmFuY2hQb2xpY3kzNjQ2NjI=",
  "name": "release/*"
}

Delete a deployment branch policy

Deletes a deployment branch or tag policy for an environment.

OAuth app tokens and personal access tokens (classic) need the repo scope to use this endpoint.

Tokens de acesso refinados para "Delete a deployment branch policy"

Esse ponto de extremidade funciona com os seguintes tipos de token refinados:

O token refinado deve ter os seguintes conjuntos de permissões:

"Administration" repository permissions (write)

Parâmetros para "Delete a deployment branch policy"

Cabeçalhos
Nome, Tipo, Descrição
`accept` string Setting to `application/vnd.github+json` is recommended.

Parâmetros de caminho
Nome, Tipo, Descrição
`owner` string Obrigatório The account owner of the repository. The name is not case sensitive.
`repo` string Obrigatório The name of the repository without the `.git` extension. The name is not case sensitive.
`environment_name` string Obrigatório The name of the environment. The name must be URL encoded. For example, any slashes in the name must be replaced with `%2F`.
`branch_policy_id` integer Obrigatório The unique identifier of the branch policy.

Códigos de status de resposta HTTP para "Delete a deployment branch policy"

Código de status	Descrição
`204`	No Content

Exemplos de código para "Delete a deployment branch policy"

Se você acessar o GitHub em GHE.com, substitua api.github.com pelo subdomínio dedicado da sua empresa em api.SUBDOMAIN.ghe.com.

Exemplo de solicitação

delete/repos/{owner}/{repo}/environments/{environment_name}/deployment-branch-policies/{branch_policy_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/repos/OWNER/REPO/environments/ENVIRONMENT_NAME/deployment-branch-policies/BRANCH_POLICY_ID

Response

Status: 204