# vagas-java: a Java job board that stores its listings in GitHub issues

> The soujava/vagas-java repository is a job wall for Java developers where a vacancy is a GitHub issue, a title convention encodes the city and company, and labels carry the experience level and contract type. The published site is generated from those issues, so the platform is GitHub itself rather than a database, and the project is maintained by the Java Dev BR Slack community.

**soujava/vagas-java** — Mural de vagas para desenvolvedores Java

- Repository: https://github.com/soujava/vagas-java
- Website: https://soujava.github.io/vagas-java/
- Stars: 1,041 · Forks: 51
- Language: TypeScript
- License: not declared
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/soujava-vagas-java

## The issue tracker is the database

The README states the design in one sentence: Espaço para a divulgação de vagas para desenvolvedores Java, utilizando via issues do GitHub. A space for the publication of vacancies for Java developers, using GitHub issues.

That is the whole architecture. There is no application server, no database, no admin panel and no user accounts. A vacancy is an issue. The catalogue of vacancies is the list of open issues with a particular label. The published website at soujava.github.io/vagas-java is a rendering of that list, and the primary link given for available vacancies is the issues page itself.

The practical consequences follow directly. A listing is created by a person with a GitHub account, in a form rather than a script, so it is a manual process with a manual error rate. It is visible, forkable and auditable in a way a proprietary job board is not. It is also permanent unless someone closes the issue, so the board accumulates stale listings unless a maintainer prunes them.

The repository layout backs the reading. There is a front-end/ directory, a docs/ directory, a _config.yml, a .github/ directory and a README.md. The _config.yml file is a Jekyll configuration, and there is a GitHub Actions workflow for building and deploying to GitHub Pages, so the site is generated from files in the repository and published to the pages URL.

The alternative to all of this is obvious and worth naming: a job board is normally a web application with a database, and a community can run one of those on a free tier. What the issue-tracker approach trades away is the job board software, and what it gets is a system that already has identity, notifications, search, moderation primitives and a mobile client.

## The title convention is the schema

Because there is no database, the conventions for how a title and a set of labels are written are the schema. The README treats them as requirements, with warning markers.

The title format is: in the issue title, place the name of the city in square brackets, followed by the name of the vacancy and the name of the company, if any. The example given is `[Cidade, Estado] Desenvolvedor Java | ACME LTDA`, which reads as city and state in brackets, then the role, then a pipe, then the company.

The pipe separator is doing real work. It is a fixed delimiter between the location and the role, which means a tool reading the titles can split on the pipe and the brackets and recover structured fields without anyone filling in a form. That is what makes the issue list queryable, and it explains why the format is recommended rather than merely suggested.

The second rule is about the label. Keep the label job opportunity to help with classification in the repository. Additional labels are added as needed, with options covering the desired experience level and the contract format.

So the classification is two-dimensional. The label job opportunity is a boolean, is this a vacancy listing, and the optional labels carry the attributes, seniority and contract type. A listing can therefore be found by experience level or by contract type without anyone parsing the body text.

This is the part of the design that scales or does not, and it depends entirely on the community holding to the convention. A single listing that ignores the title format breaks any tool that reads the titles, and the failure is silent.

## The issue template, and what a listing should contain

Posting a vacancy starts with a template. Create an issue by selecting the template Adicionar uma nova oportunidade de trabalho / Adicionar nova vaga, through the link to the repository's issues/new/choose page.

The README notes that the template already provides a specific model, and that you can edit it as you like, but recommends some details.

That is the design working as intended. The template is a scaffold rather than a schema, which means a poster can add the fields their posting needs, and the conventions in the title and labels are the only machine-readable parts. This is the standard split in a community that values low friction over strict form compliance, and it is a real trade: a strict template would guarantee every listing has a salary range and a remote flag, and a loose one guarantees almost nobody fills in the optional parts.

The workflow is therefore: open the issues/new/choose page, pick the job opportunity template, fill it in, write the title in the city, state, role, company form, and apply the job opportunity label plus any attribute labels.

The published site is at soujava.github.io/vagas-java, and the same content is reachable through the issues list, with the README pointing to both.

The second workflow, which is the one that makes the board maintainable, is that a poster updates the issue when the vacancy is filled or changed, and a maintainer closes it. That is the entire lifecycle management, and it depends on the poster coming back to the issue rather than posting a new one.

## A code of conduct borrowed rather than written

The code of conduct section is short and candid about its own gap.

It states that there is not yet a specific code of conduct for the creation of vacancies, but that there is a code of conduct for the Java Dev BR Slack itself, and that the authors believe this job board also follows what they believe in the community as a whole. The link points to the soujava/codigo-de-conduta-slack-javadevbr repository.

Reusing a document rather than writing a parallel one is the right instinct, and the admission that the borrowed one is imperfect is better than pretending otherwise. The gap it leaves is real, though. The Slack code of conduct governs behaviour in a chat room. A job board governs what a recruiter may post about a role, whether a listing is genuine, and how complaints about a misleading posting are handled. Those are different problems, and the Slack document is unlikely to address them.

The consequence for a poster is that the rules about what may be advertised are implicit. The README does not describe a policy on salary disclosure, on whether recruiters must identify themselves as recruiters, on what happens to a fraudulent listing, or on how a report about a listing is handled. A poster who wants to know the rules has to read a code of conduct written for a different context.

The issues page is where moderation would happen in practice, and the repository's own label set, which includes a level of experience and a contract format, suggests the maintainers think in terms of metadata. Extending that to a moderation label would be a small step, and it is the kind of thing that a README could state explicitly.

## One board inside a network of boards

The last third of the README is a directory of sibling job boards, and it is the most useful part for anyone looking for a role.

The README is explicit that this repository is specific to Java vacancies. It then lists the other lists where you can post a vacancy too, organised by area and by technology.

By area there are back-end, front-end, chat-bot, data science, UI/UX and QA boards. By technology there are boards for Android, iOS and OSX, PHP, Python, Vue.js, Go and Golang, Flutter, React and React Native, .NET, Rust, Elm and Kotlin. By locality there are boards for Ceará, for Feira de Santana in Bahia, and separate front-end and back-end boards for Angola and for Portugal.

The mechanism behind the split is described in the README: some people from the community forked the FrontEndBR repository and created other lists specific to different stacks and states of the country.

That is worth pausing on, because it is the opposite of consolidation. A single board with better search would be easier to use, and instead the ecosystem has fragmented into dozens of boards that each own a slice. The reason is not technical. Forking a repository is free and instant, and a community organiser who wants a Kotlin board does not have to ask anyone's permission. The cost is that a searcher now has to check a dozen lists.

The directory in the README is therefore doing the job a search engine would do, which is the most sensible thing available given the structure. It is also the thing that will fall out of date first, since every new fork has to be added by hand.

## A static site built by two workflows

The two CI badges at the top of the README describe how the project is built and shipped.

There is a Build and Test workflow, at .github/workflows/build-test.yml, and a Build and Deploy to GitHub Pages workflow, at .github/workflows/github-pages.yml. The primary language is recorded as TypeScript, and the repository contains a front-end/ directory, so the front end is a TypeScript project that is built and then rendered into a static site, with the _config.yml holding the Jekyll configuration that ties the generated output to the pages deployment.

That is a reasonable setup for this kind of board. The issues are the data, the front end reads them through the GitHub API, and the generated site is the readable view of the same data. The deploy workflow means the published board is a static artefact, which is cheap to host and cannot go down independently of the page generator.

The Build and Test workflow is the one that matters for a contributor, because it is what tells you whether a change to the front end is acceptable. And the repository has no GitHub releases, with the last push on 2026-10-14, so the site is the deployment artefact and there is nothing else to version.

The licence for the repository is listed as unknown. For a repository whose main content is community-submitted job listings, that is understandable, since the listings are contributed text and the front end is a thin wrapper, but it does mean an organisation that wanted to reuse the front end code would need to ask rather than rely on a stated grant.

## Conclusion

vagas-java suits a Java developer looking for a role in Brazil who is comfortable with GitHub as a front end, since every listing is an issue you can read, label and comment on, and the whole thing is searchable without an account. It is the wrong tool if you need an application tracking system, a recruiter pipeline or any notion of a vacancy expiring, because there is no server and no state beyond the issue tracker. Before you post a listing, follow the issue template and keep the job opportunity label, since the README names that label as the mechanism the repository uses for classification, and check the linked community code of conduct, which the project reuses rather than writing its own.

## FAQ

### How do I post a job vacancy on vagas-java?

Open the repository's issues/new/choose page and select the template for adding a new job opportunity, then fill it in. The README asks that the issue title put the city and state in square brackets followed by the role and company, for example [Cidade, Estado] Desenvolvedor Java | ACME LTDA.

### Where can I see the Java job listings?

On the published site at soujava.github.io/vagas-java and in the repository's issues list at github.com/soujava/vagas-java/issues. The README links both as the places where available vacancies can be found.

### What do the labels on a vagas-java issue mean?

The job opportunity label should be kept so the repository can classify the listing, and additional labels can be added where needed, with options covering the desired experience level and the contract format.

### Does vagas-java have its own code of conduct?

Not yet. The README says there is no specific code of conduct for creating vacancies, but that the code of conduct for the Java Dev BR Slack applies, and it links to the soujava/codigo-de-conduta-slack-javadevbr repository.

### Are there job boards for other stacks than Java?

Yes, the README lists sibling boards by area, by technology and by locality, including back-end, front-end, data science, Android, Python, Go, .NET, Rust, Kotlin and regional boards for Ceará, Feira de Santana, Angola and Portugal, some of them created by forking the FrontEndBR repository.

## Sources

- [Issues](https://github.com/soujava/vagas-java/issues)
- [Project website](https://soujava.github.io/vagas-java/)
- [README](https://github.com/soujava/vagas-java/blob/main/README.md)
- [soujava/vagas-java on GitHub](https://github.com/soujava/vagas-java)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/soujava-vagas-java