O material será útil para iniciantes e aqueles que desejam criar CI / CD rapidamente para látex com ferramentas integradas do GitHub.
Introdução
Outro dia, enquanto navegava no repositório com meu currículo (estou fazendo isso em látex, felizmente, existem muitos modelos ), pensei que seria bom organizar algum tipo de lugar onde a versão atual do documento sempre se encontra.
Os requisitos básicos eram simples:
- Com esforço mínimo para aumentar o site com lançamentos;
- Faça atualizações de conteúdo no site automáticas.
Uma solução na forma de um pipeline foi desenhada em minha cabeça:
- Envie a confirmação para o GitHub;
- Criação de arquivos .tex em CI / CD;
- Envio de pdfs coletados para versões do GitHub;
- Atualizando arquivos PDF no site do cartão de visita.
Neste artigo, examinaremos mais de perto cada etapa. O site será o GitHub Pages. Para CI / CD, usaremos Ações GitHub.
Nós precisamos:
- Conta GitHub;
- Ferramentas de compilação LaTeX;
- Qualquer editor de texto (estou usando o VIM configurado para latex );
Ir!
Conectando ações do GitHub
Aqui, todas as ações podem ser realizadas a partir do site sem recorrer ao console.
Vá para "Ações" (sublinhado em vermelho).
e encontrar o cartão "Fluxo de trabalho simples", onde pressionamos o botão "Configurar este fluxo de trabalho"
Um editor com um modelo de fluxo de trabalho será aberto na nossa frente. Vale a pena insistir nesse ponto com mais detalhes.
Ações do GitHub funcionam com fluxos de trabalho , que são descritos em arquivos separados. Cada fluxo de trabalho consiste em:
- Nome (seção
name: …); - Condições de início (seção
on: …); - Lista de tarefas a serem realizadas (seção
jobs: …)
Cada trabalho também consiste em pedaços menores chamados de etapa . Cada etapa é uma ação atômica (feita de uma vez). Nesse caso, a etapa tem seu próprio nome (
name: …) e uma lista de comandos ( run: …), e também pode usar uma ação pronta ( uses: …) de desenvolvedores terceiros. Ações de
terceiros são a parte mais poderosa das Ações do GitHub. Eles podem fazer muitas coisas: instalar o JDK , executar testes python em tox e muito mais. Neste tutorial, usaremos xu-cheng / latex-action @ v2 para compilar o látex (não houve problemas com o cirílico) eactions / upload-artifact @ v2 para fazer upload de artefatos.
Voltemos ao nosso editor. O template proposto pode ser corrigido, trazendo-o para o formulário:
name: Build and deploy latex sources to GitHub Pages
on: push
jobs:
build:
# , . ubuntu
runs-on: ubuntu-latest
steps:
# action,
- uses: actions/checkout@v2
#
- name: Build document
uses: xu-cheng/latex-action@v2
with:
# ,
root_file: main.tex
# .
working_directory: latex_sources/
# , (latexmk)
# -jobname=<name>
args: -jobname=my_doc -pdf -file-line-error -halt-on-error -interaction=nonstopmode
compiler: latexmk
# pdf-
- name: Upload pdf document
uses: actions/upload-artifact@v2
with:
#
name: my_doc
# pdf. «*», «**»
# <working_directory>/<jobname>.pdf
path: latex_sources/my_doc.pdf
Salve-o em um arquivo, escolha qualquer nome para o arquivo (você pode usar latex.yml). Após submeter a criação do arquivo aos editores da web, a primeira compilação deve ir para Ações do GitHub, como resultado do qual um artefato aparecerá - o pdf compilado.
Hooray! Agora você pode começar a lançar.
Configurando lançamentos automáticos
O sistema de liberação no GitHub tem uma peculiaridade: uma liberação está sempre ligada a um commit com uma tag. Portanto, temos duas opções:
- Adicione tags manualmente para aqueles commits para os quais queremos coletar e liberar arquivos pdf;
- Identifique automaticamente todos os commits e libere-os.
Para mim, a segunda opção parecia mais conveniente. Eu geralmente faço commit e push exatamente quando o trabalho é concluído (logicamente ou para hoje). Portanto, no futuro falarei sobre ele.
Para criar uma versão, usaremos a ação actions / create-release @ v1 e para fazer o upload do arquivo pdf para a versão criada (sim, ele é carregado separadamente) usaremos actions / upload-release-asset @ v1 .
Vamos adicionar um novo emprego:
deploy:
runs-on: ubuntu-latest
# master. ,
if: github.ref == 'refs/heads/master'
# job. .
needs: [build]
steps:
# , bash-
- name: Variables
# id : step
id: vars
# echo ${{ steps.<step_id>.outputs.<variable_name> }}
# | — yaml. ,
run: |
echo «::set-output name=date::$(date +'%Y-%m-%d')»
echo «::set-output name=sha8::$(echo ${GITHUB_SHA} | cut -c1-8)»
- name: Download artifacts
uses: actions/download-artifact@v2
with:
# , upload-artifact
name: my_doc
- name: Create Release
uses: actions/create-release@v1
id: create_release
env:
# ., GITHUB_TOKEN
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # This token is provided by Actions
with:
# step id=vars (. ).
# “my_doc-< >-< 8 sha >
tag_name: my_doc-${{ steps.vars.outputs.date }}-${{ steps.vars.outputs.sha8 }}
# ,
release_name: My Actions document (version ${{ steps.vars.outputs.date }})
# , false
draft: false
prerelease: false
# step
- name: Upload pdf asset
uses: actions/upload-release-asset@v1
env:
#
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
# step id=create_release upload_url —
upload_url: ${{ steps.create_release.outputs.upload_url }}
# latex_sources, download-artifacts
asset_path: ./my_doc.pdf
# ,
asset_name: my_asset_name.pdf
asset_content_type: application/pdf
Adicione ao arquivo de fluxo de trabalho, confirme as alterações. Vá para Ações e veja se mais uma etapa foi adicionada:
Ao mesmo tempo, o pdf compilado também apareceu em lançamentos.
A única coisa que resta é fazer o upload para o site.
Abrindo páginas do GitHub
O GitHub permite que cada projeto crie uma página da web e oferece hospedagem gratuita para ela. Mas você não precisa saber JS / CSS / HTML para escrever algo que valha a pena! Fora da caixa, o serviço oferece vários modelos bonitos que resolvem completamente o problema de layout. Tudo que você precisa fazer é preencher o documento Markdown, e o sistema faz o resto.
Vamos para a seção "Configurações" do repositório e na guia "Opções" (aberta primeiro por padrão), role para baixo até "Páginas do GitHub".
Aqui, selecionamos o branch master como a fonte e / docs como a pasta (você também pode usar / root, mas prefiro manter o número mínimo de arquivos na raiz do projeto). Clique em "Salvar".
O botão "Theme Chooser" abre uma galeria de modelos, onde cada um pode ser acessado, visualizado e selecionado clicando no botão verde "Select theme".
Após a escolha de um tema, seremos lançados no editor web, onde se propõe a edição do arquivo Markdown, que passará a ser o site. Aqui você pode descrever tudo o que seu coração deseja: desde uma simples apresentação de si mesmo até os objetivos do documento e as características do trabalho.
Quando estiver satisfeito com o conteúdo, envie suas alterações.
Onde está minha página?
O link para a página montada é sempre armazenado em Configurações -> Páginas do GitHub. É melhor registrá-lo no site do repositório (a engrenagem ao lado do campo "Sobre" na página principal) para não perdê-lo.
Baixando a versão mais recente
Há um pequeno truque: a versão mais recente e todos os seus arquivos sempre podem ser referenciados substituindo a tag de confirmação na URL por "mais recente". Em nosso exemplo, para obter o arquivo my_asset_name.pdf da versão mais recente, precisamos inserir um link
https://github.com/<your_username>/<repo_name>/releases/latest/download/my_asset_name.pdf.
No meu caso, foi: https://github.com/alekseik1/github_actions_latex_template/releases/latest/download/my_asset_name.pdf .
Após essas etapas, as páginas do GitHub sempre serão vinculadas à versão mais recente.
Resultado
Configuramos o GitHub Actions para construir automaticamente um arquivo pdf, colocá-lo no lançamento e criar um site nas páginas do GitHub contendo a versão mais recente. A versão final do projeto pode ser encontrada aqui .
Obrigado pela atenção!