> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Go: deploys pelo GitHub

> Faça deploy a partir do GitHub com c.Apps.Deploys: configure um webhook, vincule um repositório pelo GitHub App da Square Cloud e leia o histórico de deploys.

`c.Apps.Deploys` conecta uma aplicação ao GitHub para que um push faça o deploy dela. Há duas formas de fazer isso: um **webhook** que você adiciona ao repositório, ou o **GitHub App da Square Cloud**.

Cada trecho abaixo roda sozinho dentro deste programa: cole um de cada vez em `main` e execute o `goimports` (veja [Executando os exemplos](/pt-br/sdks/go/client#executando-os-exemplos)).

```go theme={"system"}
package main

import (
	"context"
	"os"

	"github.com/squarecloudofc/sdk-api-go/v3"
)

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456"
)

func main() {
	// Paste one snippet here, then run goimports.
}
```

## Webhook

`Deploys.SetWebhook(ctx, appID, accessToken)` configura deploys via webhook do GitHub com um token de acesso do GitHub (`ghp_...` ou `github_pat_...`) e retorna a URL do webhook a ser adicionada ao seu repositório.

```go theme={"system"}
url, err := c.Apps.Deploys.SetWebhook(ctx, appID, os.Getenv("GITHUB_TOKEN"))
if err != nil {
	log.Fatal(err)
}

fmt.Println(url) // add it as a webhook in the repository settings
```

Passe `"@"` como token para remover o webhook. O método então retorna `""`.

```go theme={"system"}
if _, err := c.Apps.Deploys.SetWebhook(ctx, appID, "@"); err != nil {
	log.Fatal(err)
}
```

Um token inválido resulta em 400 `INVALID_ACCESS_TOKEN`.

## GitHub App

`Deploys.LinkGithubApp(ctx, appID, repository, branch)` vincula um repositório instalado pelo GitHub App da Square Cloud. Requer o escopo `apps:deploy`.

```go theme={"system"}
repo, err := c.Apps.Deploys.LinkGithubApp(ctx, appID, "octocat/hello-world", "main")
if err != nil {
	log.Fatal(err)
}

fmt.Println(repo.ID, repo.FullName, repo.Branch)
```

`Deploys.UnlinkGithubApp(ctx, appID)` remove o vínculo. Para vincular outro repositório ou branch, desvincule primeiro.

```go theme={"system"}
if err := c.Apps.Deploys.UnlinkGithubApp(ctx, appID); err != nil {
	log.Fatal(err)
}
```

Vincular e desvincular compartilham um limite de **3 chamadas a cada 60 segundos**.

| Status | Código | Quando |
| - | - | - |
| 400 | `GIT_ALREADY_CONFIGURED` | A aplicação já tem um repositório vinculado: desvincule-o primeiro |
| 400 | `GIT_NOT_CONFIGURED` | `UnlinkGithubApp` sem nada vinculado |
| 400 | `BRANCH_NOT_FOUND`, `INVALID_BRANCH_LENGTH` | A branch não existe, ou seu nome tem mais de 256 caracteres |
| 403 | `GITHUB_NOT_CONNECTED` | Sua conta não tem uma instalação do GitHub App |
| 403 | `REPOSITORY_NOT_AVAILABLE` | O GitHub App não está instalado no repositório por meio da sua conta do GitHub |
| 403 | `REPOSITORY_PERMISSION_REQUIRED` | Sua conta do GitHub não tem acesso de escrita ao repositório |
| 404 | `REPOSITORY_NOT_FOUND` | O repositório não existe ou não está visível |
| 409 | `REPOSITORY_BRANCH_ALREADY_CONFIGURED` | Outra aplicação, de qualquer conta, já vincula este repositório e branch. O id dela aparece em `Message` apenas quando essa aplicação é sua |
| 502 | `FAILED_TO_FETCH` | O GitHub não confirmou a branch: é seguro tentar novamente |

## Configuração atual

`Deploys.Current(ctx, appID)` retorna o que está configurado: `App` para o vínculo do GitHub App, `Webhook` para a URL do webhook. Quando nada está configurado, retorna o valor zero (`App` é `nil` e `Webhook` é `""`). Os campos de `App` são ponteiros, já que a API pode enviá-los como `null`.

```go theme={"system"}
current, err := c.Apps.Deploys.Current(ctx, appID)
if err != nil {
	log.Fatal(err)
}

if app := current.App; app != nil && app.Name != nil && app.Branch != nil {
	fmt.Println(*app.Name, *app.Branch) // e.g. "octocat/hello-world" "main"
}
if current.Webhook != "" {
	fmt.Println(current.Webhook)
}
```

## Histórico de deploys

`Deploys.List(ctx, appID)` retorna uma **linha do tempo por deploy** (um `[][]DeployEvent`), cada uma um slice de eventos, do evento mais antigo para o mais recente. Apenas deploys via Git (pushes por webhook e GitHub App) são registrados.

```go theme={"system"}
timelines, err := c.Apps.Deploys.List(ctx, appID)
if err != nil {
	log.Fatal(err)
}
for _, timeline := range timelines {
	if len(timeline) == 0 {
		continue
	}
	last := timeline[len(timeline)-1]
	fmt.Println(last.ID, last.State, last.Date)

	if last.State == squarecloud.DeployError {
		fmt.Println(last.Code, last.Message)
	}
}
```

| Campo | Descrição |
| - | - |
| `ID` (`id`) | O SHA do commit |
| `State` (`state`) | `pending`, `clone`, `commit`, `restarting`, `success` ou `error` (constantes `DeployPending`, `DeployClone`, `DeployCommit`, `DeployRestarting`, `DeploySuccess`, `DeployError`) |
| `Date` (`date`) | Quando o evento aconteceu (`time.Time`) |
| `Source` (`source`) | Sempre `"git"` |
| `Branch` (`branch`) | Em eventos `clone` |
| `Files` (`files`) | Em eventos `commit`: um `*DeployFiles` com `Added`, `Removed` e `Modified`; `nil` nos demais |
| `Code` / `Message` (`code` / `message`) | Em eventos `error`: por que o deploy falhou (por exemplo, `CLONE_FAILED`) |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Rede" icon="globe" href="/pt-br/sdks/go/network">
    Analytics, DNS, domínios personalizados e cache.
  </Card>

  <Card title="Referência da API de deploy" icon="code" href="/pt-br/api-reference/endpoint/apps/deploy/list">
    Os endpoints REST por trás destes métodos.
  </Card>

  <Card title="Deploys do GitHub pela CLI" icon="terminal" href="/pt-br/cli-reference/github-deploys">
    As mesmas ações pelo terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.